@ipul-labs/forge 1.14.0 → 1.15.0

package/server/forge/core/ForgeAgent.test.js

@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// We test the module-level helpers and ForgeAgent internals by importing the
+// module. The class constructor requires a project, so we mock the provider.
+// For the pure functions (buildCommitSubject, FILE_CAPS), we test them through
+// a thin wrapper or by constructing a ForgeAgent with mocked providers.
+
+// ─── Module-level helpers ────────────────────────────────────────────────────
+
+// buildCommitSubject and FILE_CAPS are not exported, so we test them through
+// ForgeAgent's public surface or by importing the module and inspecting.
+// Since they're internal, we test via the class methods that use them.
+
+import * as configStore from "./configStore.js";
+
+// Mock configStore.getPrimaryProject for ForgeAgent constructor
+vi.spyOn(configStore, "getPrimaryProject").mockReturnValue("group/web-app");
+vi.spyOn(configStore, "get").mockReturnValue({
+	repos: [{ id: "group/web-app", label: "web-app" }],
+	defaults: { promptRules: "" },
+	connections: {},
+});
+
+// Mock the provider factory
+vi.mock("./providers/index.js", () => ({
+	createProvider: () => ({
+		getIssue: vi.fn(),
+		getFileTree: vi.fn().mockResolvedValue([]),
+		getFileContent: vi.fn(),
+		createBranch: vi.fn(),
+		commitFiles: vi.fn(),
+		createMR: vi.fn(),
+		listAllForgeMRs: vi.fn().mockResolvedValue([]),
+		getMRPipelines: vi.fn().mockResolvedValue([]),
+	}),
+}));
+
+// Dynamic import after mocks are set up
+const { ForgeAgent } = await import("./ForgeAgent.js");
+
+describe("ForgeAgent", () => {
+	describe("_capSelections", () => {
+		let agent;
+
+		beforeEach(() => {
+			agent = new ForgeAgent({ project: "group/web-app" });
+		});
+
+		it("applies fix caps (12 total, 8 per repo)", () => {
+			const entries = Array.from({ length: 15 }, (_, i) => ({
+				repo: "group/web-app",
+				path: `src/file${i}.ts`,
+			}));
+
+			const capped = agent._capSelections(entries, "fix");
+			expect(capped).toHaveLength(8);
+		});
+
+		it("applies feature caps (18 total, 15 per repo)", () => {
+			const entries = Array.from({ length: 20 }, (_, i) => ({
+				repo: "group/web-app",
+				path: `src/file${i}.ts`,
+			}));
+
+			const capped = agent._capSelections(entries, "feature");
+			expect(capped).toHaveLength(15);
+		});
+
+		it("enforces total cap across multiple repos for features", () => {
+			const entries = [
+				...Array.from({ length: 12 }, (_, i) => ({
+					repo: "group/web-app",
+					path: `src/file${i}.ts`,
+				})),
+				...Array.from({ length: 12 }, (_, i) => ({
+					repo: "group/api",
+					path: `internal/file${i}.go`,
+				})),
+			];
+
+			const capped = agent._capSelections(entries, "feature");
+			expect(capped).toHaveLength(18);
+		});
+
+		it("defaults to fix caps for unknown kinds", () => {
+			const entries = Array.from({ length: 15 }, (_, i) => ({
+				repo: "group/web-app",
+				path: `src/file${i}.ts`,
+			}));
+
+			const capped = agent._capSelections(entries, "unknown");
+			expect(capped).toHaveLength(8);
+		});
+
+		it("refactor gets same caps as feature", () => {
+			const entries = Array.from({ length: 20 }, (_, i) => ({
+				repo: "group/web-app",
+				path: `src/file${i}.ts`,
+			}));
+
+			const capped = agent._capSelections(entries, "refactor");
+			expect(capped).toHaveLength(15);
+		});
+	});
+
+	describe("_normalizeFileSelections", () => {
+		let agent;
+
+		beforeEach(() => {
+			agent = new ForgeAgent({ project: "group/web-app" });
+		});
+
+		it("normalizes string entries to primary repo", () => {
+			const result = agent._normalizeFileSelections(["src/App.tsx"]);
+			expect(result).toEqual([{ repo: "group/web-app", path: "src/App.tsx" }]);
+		});
+
+		it("passes through {repo, path} objects", () => {
+			const result = agent._normalizeFileSelections([
+				{ repo: "group/api", path: "main.go" },
+			]);
+			expect(result).toEqual([{ repo: "group/api", path: "main.go" }]);
+		});
+
+		it("defaults repo when only path is present", () => {
+			const result = agent._normalizeFileSelections([{ path: "src/a.ts" }]);
+			expect(result).toEqual([{ repo: "group/web-app", path: "src/a.ts" }]);
+		});
+
+		it("filters out null and invalid entries", () => {
+			const result = agent._normalizeFileSelections([null, undefined, {}, "src/a.ts"]);
+			expect(result).toHaveLength(1);
+			expect(result[0].path).toBe("src/a.ts");
+		});
+	});
+
+	describe("_validateSelections", () => {
+		let agent;
+
+		beforeEach(() => {
+			agent = new ForgeAgent({ project: "group/web-app" });
+		});
+
+		it("keeps files that exist in the tree", () => {
+			const entries = [{ repo: "group/web-app", path: "src/App.tsx" }];
+			const trees = [{ repo: "group/web-app", files: ["src/App.tsx", "src/index.ts"] }];
+			const { valid, skipped } = agent._validateSelections(entries, trees);
+			expect(valid).toHaveLength(1);
+			expect(skipped).toHaveLength(0);
+		});
+
+		it("skips files not in the tree", () => {
+			const entries = [{ repo: "group/web-app", path: "src/Missing.tsx" }];
+			const trees = [{ repo: "group/web-app", files: ["src/App.tsx"] }];
+			const { valid, skipped } = agent._validateSelections(entries, trees);
+			expect(valid).toHaveLength(0);
+			expect(skipped).toHaveLength(1);
+			expect(skipped[0]).toContain("not in tree");
+		});
+
+		it("skips files from unknown repos", () => {
+			const entries = [{ repo: "group/unknown", path: "src/a.ts" }];
+			const trees = [{ repo: "group/web-app", files: ["src/a.ts"] }];
+			const { valid, skipped } = agent._validateSelections(entries, trees);
+			expect(valid).toHaveLength(0);
+			expect(skipped[0]).toContain("unknown repo");
+		});
+
+		it("deduplicates entries", () => {
+			const entries = [
+				{ repo: "group/web-app", path: "src/App.tsx" },
+				{ repo: "group/web-app", path: "src/App.tsx" },
+			];
+			const trees = [{ repo: "group/web-app", files: ["src/App.tsx"] }];
+			const { valid } = agent._validateSelections(entries, trees);
+			expect(valid).toHaveLength(1);
+		});
+	});
+});

package/server/forge/core/claudeClient.js

@@ -14,6 +14,7 @@ import { spawn } from "child_process";
 import {
 	SELECT_FILES_SCHEMA,
 	PROPOSE_FIX_SCHEMA,
+	CI_FIX_SCHEMA,
 	REFINE_OR_ASK_SCHEMA,
 	RESOLUTION_CHECK_SCHEMA,
 	buildIdentifyFilesPrompt,
@@ -21,6 +22,7 @@ import {
 	buildRefineOrAskPrompt,
 	buildRefineResumePrompt,
 	buildCheckResolutionPrompt,
+	classifyIssue,
 } from "./prompts.js";
 
 // FORGE_MODEL env var overrides the default. Set to a cheaper model to reduce cost.
@@ -332,10 +334,25 @@ Your final message MUST be a single raw JSON object matching the schema — no p
 }
 
 export async function proposeFix(issue, fileContents, options = {}, model, opts = {}) {
-	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } = await runClaude(
-		buildProposeFixPrompt(issue, fileContents, options),
-		PROPOSE_FIX_SCHEMA,
-		`You are Forge, an AI code assistant in a production React/TypeScript/Express codebase.
+	const schema = options.ciContext ? CI_FIX_SCHEMA : PROPOSE_FIX_SCHEMA;
+	const kind = classifyIssue(issue);
+	const isFeature = kind === "feature" || kind === "refactor";
+
+	const systemPrompt = isFeature
+		? `You are Forge, an AI code assistant in a production React/TypeScript/Express codebase.
+Rules:
+- Match the existing code style exactly (TypeScript strict, no barrel imports, Tailwind for UI).
+- For "proposed", always return the COMPLETE file content, not a diff or snippet.
+- Maximum 12 files changed. Prioritise core changes over secondary ones — if the feature touches more files than the cap, implement the most important changes and note the rest in "explanation".
+- Never add console.* — use the existing log utility.
+- Never add comments unless the logic is non-obvious.
+- Before returning, verify TypeScript correctness: no implicit any, no missing imports, no type mismatches, all imported symbols must actually be exported from their source.
+Feature discipline:
+- Follow the issue specification. Only make changes the issue asks for — do not clean up, refactor, or "improve" unrelated code.
+- When the issue says to ADD an entry to an existing list or config (nav items, routes, type unions), add the entry — do not restructure the existing code around it.
+- Base new files on the patterns and conventions visible in the relevant files.
+- Use a "feat:" conventional-commit prefix in the title, not "fix:".`
+		: `You are Forge, an AI code assistant in a production React/TypeScript/Express codebase.
 Rules:
 - Changes must be minimal and surgical.
 - Match the existing code style exactly (TypeScript strict, no barrel imports, Tailwind for UI).
@@ -348,7 +365,12 @@ Rules:
 Root-cause discipline:
 - A fix that only improves an error message or adds a guard at the point of failure is a symptom suppressor, not a fix. Reject it and find the upstream origin of the bad input.
 - When a value is undefined/null at a check, trace one or two frames up (the caller of the function, the prop passed into the component, the handler bound to an onClick). Default function parameters are defeated when the caller passes an unexpected argument (e.g. React forwarding a MouseEvent) — look for that class of bug before patching the consumer.
-- In "explanation", name the origin of the bad value and state why the reported symptom can no longer occur after your change.`,
+- In "explanation", name the origin of the bad value and state why the reported symptom can no longer occur after your change.`;
+
+	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } = await runClaude(
+		buildProposeFixPrompt(issue, fileContents, options),
+		schema,
+		systemPrompt,
 		model,
 		{ signal: opts.signal },
 	);

package/server/forge/core/configStore.js

@@ -30,6 +30,7 @@ import path from "node:path";
  *     agent: string | null,
  *     autoPushOnValidatePass: boolean,
  *     refineRepoAccess: boolean,
+ *     promptRules: string,
  *   },
  *   connections: {
  *     gitlab: GitLabConnection,
@@ -55,6 +56,9 @@ const DEFAULT_CONFIG = {
 		// clone of the primary repo. Off → lighter "file tree in prompt" flow.
 		// The FORGE_REFINE_REPO_ACCESS env var, when set, overrides this.
 		refineRepoAccess: true,
+		// Free-form rules injected into every analysis and refine prompt.
+		// Lets the user steer the model without touching code.
+		promptRules: "",
 		// Test-deploy URL surfaced next to "Approve & Create MR" when the
 		// branch pipeline is green. Plain URL (e.g. "https://test.example.com")
 		// for a shared env; supports "{branch}" / "{slug}" placeholders when
@@ -153,6 +157,17 @@ export function reload() {
 	return cache;
 }
 
+/**
+ * Resolves the primary project identifier.
+ * Priority: persisted config repos[0] → FORGE_REPOS first entry → FORGE_GITLAB_PROJECT.
+ */
+export function getPrimaryProject() {
+	const repos = cache.repos;
+	if (repos.length > 0) return repos[0].id;
+	const raw = process.env.FORGE_REPOS ?? process.env.FORGE_GITLAB_PROJECT ?? "";
+	return raw.split(",")[0]?.trim() || null;
+}
+
 const ENV_TOKEN_KEYS = {
 	gitlab: "GITLAB_TOKEN",
 	github: "GITHUB_TOKEN",

package/server/forge/core/configStore.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// We test getPrimaryProject and getConnection which resolve from
+// cache (configStore state) → env vars → defaults.
+
+import { getPrimaryProject, getConnection, get, reload } from "./configStore.js";
+
+describe("getPrimaryProject", () => {
+	const originalEnv = { ...process.env };
+
+	afterEach(() => {
+		process.env = { ...originalEnv };
+	});
+
+	it("returns first config repo when config has repos", () => {
+		const cfg = get();
+		// If the test env has repos in config, this tests the real path.
+		// Otherwise we test the env fallback paths below.
+		if (cfg.repos.length > 0) {
+			expect(getPrimaryProject()).toBe(cfg.repos[0].id);
+		}
+	});
+
+	it("falls back to FORGE_REPOS first entry", () => {
+		// Temporarily clear config repos by checking current state
+		const cfg = get();
+		if (cfg.repos.length === 0) {
+			process.env.FORGE_REPOS = "group/web-app,group/api";
+			expect(getPrimaryProject()).toBe("group/web-app");
+		}
+	});
+
+	it("falls back to FORGE_GITLAB_PROJECT when FORGE_REPOS is unset", () => {
+		const cfg = get();
+		if (cfg.repos.length === 0) {
+			delete process.env.FORGE_REPOS;
+			process.env.FORGE_GITLAB_PROJECT = "legacy/project";
+			expect(getPrimaryProject()).toBe("legacy/project");
+		}
+	});
+
+	it("returns null when nothing is configured", () => {
+		const cfg = get();
+		if (cfg.repos.length === 0) {
+			delete process.env.FORGE_REPOS;
+			delete process.env.FORGE_GITLAB_PROJECT;
+			expect(getPrimaryProject()).toBeNull();
+		}
+	});
+
+	it("trims whitespace from FORGE_REPOS entries", () => {
+		const cfg = get();
+		if (cfg.repos.length === 0) {
+			process.env.FORGE_REPOS = "  group/web-app , group/api ";
+			expect(getPrimaryProject()).toBe("group/web-app");
+		}
+	});
+});
+
+describe("getConnection", () => {
+	const originalEnv = { ...process.env };
+
+	afterEach(() => {
+		process.env = { ...originalEnv };
+	});
+
+	it("returns token from env when config has none", () => {
+		process.env.GITLAB_TOKEN = "test-token-123";
+		const conn = getConnection("gitlab");
+		// Config token takes precedence, so if config has one we get that.
+		// Either way, we should get a non-empty token.
+		expect(conn.token).toBeTruthy();
+	});
+
+	it("returns a baseUrl for gitlab", () => {
+		const conn = getConnection("gitlab");
+		expect(conn.baseUrl).toContain("gitlab.com");
+	});
+
+	it("returns empty token when nothing is configured", () => {
+		delete process.env.GITLAB_TOKEN;
+		const cfg = get();
+		// Only test if config also has no token
+		if (!cfg.connections?.gitlab?.token) {
+			const conn = getConnection("gitlab");
+			expect(conn.token).toBe("");
+		}
+	});
+});

package/server/forge/core/localRepo.js

@@ -18,6 +18,8 @@ import fs from "fs/promises";
 import os from "os";
 import path from "path";
 
+import { getConnection } from "./configStore.js";
+
 const CACHE_ROOT = process.env.FORGE_VALIDATE_CACHE
 	?? path.join(os.homedir(), ".forge", "cache");
 
@@ -53,8 +55,8 @@ function sanitizeRepo(repo) {
 }
 
 function gitlabCloneUrl(project) {
-	const token = process.env.GITLAB_TOKEN;
-	if (!token) throw new Error("GITLAB_TOKEN is required to clone the repo locally.");
+	const { token } = getConnection("gitlab");
+	if (!token) throw new Error("GitLab token is required to clone the repo locally. Set it in Settings → Connections or via GITLAB_TOKEN env var.");
 	return `https://oauth2:${token}@gitlab.com/${project}.git`;
 }
 

package/server/forge/core/prompts.js

@@ -61,6 +61,43 @@ export const PROPOSE_FIX_SCHEMA = JSON.stringify({
 	required: ["title", "explanation", "changes"],
 });
 
+export const CI_FIX_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: {
+		unfixable: {
+			type: "boolean",
+			description: "True ONLY when the failure cannot be resolved by any source-code or package.json change (e.g. Docker registry outage, runner OOM, flaky network). Default false.",
+		},
+		unfixableReason: {
+			type: "string",
+			description: "Required when unfixable=true. One sentence explaining why no code change can fix this.",
+		},
+		title: {
+			type: "string",
+			description: "Conventional-commit MR title describing the actual fix, e.g. 'fix: resolve token refresh race condition in AuthService'. Max 72 chars. No issue number.",
+		},
+		explanation: {
+			type: "string",
+			description: "2-4 sentences on root cause and approach. If changes span multiple repos, describe how the pieces fit together.",
+		},
+		changes: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					repo: { type: "string", description: "Repository id this change belongs to, exactly as given in the 'Available repositories' list." },
+					file: { type: "string", description: "Path from that repo's root." },
+					action: { type: "string", enum: ["create", "modify", "delete"] },
+					proposed: { type: "string", description: "For create/modify: the COMPLETE new file content. For delete: empty string." },
+					summary: { type: "string", description: "One sentence describing this file's change." },
+				},
+				required: ["repo", "file", "action", "proposed", "summary"],
+			},
+		},
+	},
+	required: ["title", "explanation", "changes"],
+});
+
 export const REFINE_OR_ASK_SCHEMA = JSON.stringify({
 	type: "object",
 	properties: {
@@ -111,6 +148,30 @@ export const RESOLUTION_CHECK_SCHEMA = JSON.stringify({
 	required: ["resolved", "reasoning"],
 });
 
+/**
+ * Classifies an issue as "feature", "fix", or "chore" from its title, labels,
+ * and description. Used to select the right prompt guidance and file caps.
+ *
+ * Priority: conventional-commit title prefix > labels > description heuristics > default "fix".
+ */
+export function classifyIssue(issue) {
+	const title = (issue.title ?? "").toLowerCase();
+	const labels = (issue.labels ?? []).map((l) => (typeof l === "string" ? l : l.name ?? "").toLowerCase());
+
+	if (/^feat[\s(:/!]/.test(title)) return "feature";
+	if (/^fix[\s(:/!]/.test(title)) return "fix";
+	if (/^chore[\s(:/!]/.test(title)) return "chore";
+	if (/^refactor[\s(:/!]/.test(title)) return "refactor";
+
+	if (labels.some((l) => l.includes("feature") || l.includes("enhancement"))) return "feature";
+	if (labels.some((l) => l.includes("bug") || l.includes("defect"))) return "fix";
+
+	const desc = (issue.description ?? "").toLowerCase();
+	if (desc.includes("## approach") || desc.includes("## frontend changes") || desc.includes("## backend")) return "feature";
+
+	return "fix";
+}
+
 /**
  * Builds a human-readable block listing each repo's file tree.
  * Accepts either:
@@ -161,17 +222,32 @@ export function buildIdentifyFilesPrompt(issue, repoTrees) {
 		? `\n\n## Multi-repo guidance\nThese repositories are deployed together as a full-stack application. If the issue genuinely requires coordinated changes in more than one repo (e.g. a new API endpoint in the backend AND its client in the frontend), select files from each affected repo. If the fix is self-contained, pick files from only one repo.`
 		: "";
 
+	const kind = classifyIssue(issue);
+	const isFeature = kind === "feature" || kind === "refactor";
+
+	const selectionRules = isFeature
+		? `Selection rules (feature implementation):
+- Focus on files that ALREADY EXIST and need modification to support the new feature.
+- Include files that serve as PATTERNS for new files the issue asks you to create (e.g. an existing page component when a new page route is needed, an existing hook when a new hook is needed).
+- Include shared registries and type files that need new entries (routes, nav items, type definitions, API endpoints).
+- When the issue specifies exact file paths to modify, prefer those paths.
+- Do NOT select files for changes the issue doesn't mention — follow the spec, don't invent work.
+- If the issue references an existing UI element (e.g. sidebar, navbar) and only asks to ADD an entry, select the data/config file that drives that element, not the rendering component (unless the issue explicitly says to change rendering logic).`
+		: `Selection rules (bug fix):
+- When a bug points at a failing assertion, guard, or validation (e.g. "undefined priceId", "X is not defined", "cannot read property of undefined"), include the IMMEDIATE CALLER(S) of that function — not just the file where the error is thrown. The bad value usually originates upstream.
+- When a bug points at an event handler or React component, include the component that renders the handler AND the handler's implementation.
+- Prefer fewer files over more, but never omit a caller when the reported symptom is a downstream consequence of input received from that caller.`;
+
+	const maxFiles = isFeature ? 15 : 10;
+
 	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
 
 Schema: {"files": [{"repo": "<repo id>", "path": "src/foo/bar.ts"}], "reasoning": "one or two sentences"}
 
-Identify the minimum set of source files (max 10 across all repos) relevant to fixing this issue.
+Identify the ${isFeature ? "set" : "minimum set"} of source files (max ${maxFiles} across all repos) relevant to ${isFeature ? "implementing" : "fixing"} this issue.
 Always use an exact repo id from the "Available repositories" list below — do not invent or abbreviate.
 
-Selection rules:
-- When a bug points at a failing assertion, guard, or validation (e.g. "undefined priceId", "X is not defined", "cannot read property of undefined"), include the IMMEDIATE CALLER(S) of that function — not just the file where the error is thrown. The bad value usually originates upstream.
-- When a bug points at an event handler or React component, include the component that renders the handler AND the handler's implementation.
-- Prefer fewer files over more, but never omit a caller when the reported symptom is a downstream consequence of input received from that caller.
+${selectionRules}
 
 ## Issue #${issue.iid}: ${issue.title}
 ${issue.description || "(no description)"}
@@ -185,9 +261,11 @@ ${renderRepoTrees(repoTrees)}`;
 }
 
 export function buildProposeFixPrompt(issue, fileContents, options = {}) {
-	const { feedback, previousChanges, ciContext, userPrompt, repos } = options;
+	const { feedback, previousChanges, ciContext, userPrompt, repos, promptRules } = options;
 
 	const filesBlock = renderFileContents(fileContents);
+	const kind = classifyIssue(issue);
+	const isFeature = kind === "feature" || kind === "refactor";
 
 	const previousBlock = previousChanges?.length
 		? `\n\n## Previous proposed changes\n${renderPreviousChanges(previousChanges)}`
@@ -198,7 +276,14 @@ export function buildProposeFixPrompt(issue, fileContents, options = {}) {
 		: "";
 
 	const ciBlock = ciContext?.trim()
-		? `\n\n## CI pipeline failure logs\nThe pipeline failed. Propose changes that fix the pipeline.\n\n${ciContext.trim()}`
+		? `\n\n## CI pipeline failure logs
+The pipeline failed. Read the logs carefully and classify the failure:
+
+1. **Code/test failure** — broken imports, type errors, failing assertions → propose the source-code fix.
+2. **Dependency audit failure** (npm audit, yarn audit) — a package has a known vulnerability → update the version constraint in package.json. Do NOT touch package-lock.json; the lock file will be regenerated automatically.
+3. **Unfixable infrastructure failure** — Docker registry outage, runner OOM, network timeout, flaky CI runner → set "unfixable": true and explain why in "unfixableReason". Return an empty "changes" array.
+
+${ciContext.trim()}`
 		: "";
 
 	const userBlock = userPrompt?.trim()
@@ -213,21 +298,39 @@ export function buildProposeFixPrompt(issue, fileContents, options = {}) {
 		? `\n\n## Multi-repo guidance\nThis is a full-stack change. If the fix requires coordinated updates in more than one repo, produce changes tagged with the correct repo for each. Make sure API shapes, types, and field names agree across repos.`
 		: "";
 
-	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
-
-Schema: {"title": "fix: concise description of the actual change (max 72 chars)", "explanation": "...", "changes": [{"repo": "<repo id>", "file": "...", "action": "modify|create|delete", "proposed": "<full file content>", "summary": "..."}]}
-
-Propose a targeted fix for this issue.
+	const rulesBlock = promptRules?.trim()
+		? `\n\n## Custom rules (from project settings — always follow these)\n${promptRules.trim()}`
+		: "";
 
-Root-cause discipline (read BEFORE writing any change):
+	const titlePrefix = isFeature ? "feat" : "fix";
+	const titleExample = isFeature
+		? `"feat: add browseable mixes section with platinum-gated publishing"`
+		: `"fix: resolve token refresh race condition in AuthService"`;
+
+	const discipline = isFeature
+		? `Feature implementation rules (read BEFORE writing any change):
+1. Follow the issue specification precisely. If the issue says to modify a specific file, modify that file. If it says to create a new file, create it. Do NOT invent changes the issue doesn't ask for.
+2. When the issue references existing components or patterns to reuse, base your implementation on the existing patterns in the "Relevant files" section.
+3. For new files, follow the naming conventions, import style, and structure of the existing codebase.
+4. Be aware of existing routes, tabs, and UI sections that may OVERLAP with what you're implementing. If the issue creates a new "/mixes" route, check whether the codebase already has mixes-related UI elsewhere (e.g. a tab inside another page) and note any conflict in "explanation".
+5. In your "explanation", state (a) which existing patterns you followed, (b) what new files you created, and (c) any conflicts or considerations the reviewer should know about.`
+		: `Root-cause discipline (read BEFORE writing any change):
 1. Identify the ORIGIN of the bad value, not just where it's observed. If a guard, assertion, or validation is failing, trace the value one or two frames up and name the caller that produced the bad input.
 2. A fix that only makes an error message clearer (e.g. replacing \`assertIsDefined(x)\` with \`if (!x) toast.error(…)\`) is NOT a fix — it is a symptom suppressor. Reject it and propose the upstream fix instead.
 3. In your "explanation", state (a) where the bad value originates, (b) why the fix closes the reported symptom end-to-end, and (c) what would have to be true for the reported error to still appear after your change.
-4. If the origin is in a file that was not selected in pass 1, your "changes" should include that file. Do not constrain yourself to only the files listed under "Relevant files" when doing so would force a symptom-level patch.
+4. If the origin is in a file that was not selected in pass 1, your "changes" should include that file. Do not constrain yourself to only the files listed under "Relevant files" when doing so would force a symptom-level patch.`;
+
+	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
+
+Schema: {"title": "${titlePrefix}: concise description of the actual change (max 72 chars)", "explanation": "...", "changes": [{"repo": "<repo id>", "file": "...", "action": "modify|create|delete", "proposed": "<full file content>", "summary": "..."}]}
+
+${isFeature ? "Implement this feature." : "Propose a targeted fix for this issue."}
+
+${discipline}
 
 ## Issue #${issue.iid}: ${issue.title}
 ${issue.description || "(no description)"}
-Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${multiNote}${previousBlock}${feedbackBlock}${ciBlock}${userBlock}
+Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${multiNote}${rulesBlock}${previousBlock}${feedbackBlock}${ciBlock}${userBlock}
 
 ## Relevant files
 ${filesBlock}`;
@@ -264,7 +367,7 @@ function renderValidationState(state) {
  * responds with EITHER a grounded answer OR a fresh changes[] payload.
  */
 export function buildRefineOrAskPrompt(issue, fileContents, options = {}) {
-	const { feedback, previousChanges, validationState, repos, repoTrees, repoAccessMode } = options;
+	const { feedback, previousChanges, validationState, repos, repoTrees, repoAccessMode, promptRules } = options;
 
 	const filesBlock = renderFileContents(fileContents);
 	const previousBlock = previousChanges?.length
@@ -283,6 +386,10 @@ export function buildRefineOrAskPrompt(issue, fileContents, options = {}) {
 		? `\n\n## Repo access\nThe current working directory is a checkout of the primary repo with the proposed changes already overlaid. Use the Read, Glob, and Grep tools to inspect any file you need before answering or refining. Do NOT claim you lack repo access.`
 		: `\n\n## Repo access\nYou have the full file tree above and the complete content of every file currently in scope. Treat these as authoritative. If you need a file not attached, name the path and ask the user to share it — do NOT claim you lack repo access.`;
 
+	const rulesBlock = promptRules?.trim()
+		? `\n\n## Custom rules (from project settings — always follow these)\n${promptRules.trim()}`
+		: "";
+
 	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
 
 Schema: {
@@ -312,7 +419,7 @@ If the message is ambiguous, prefer "answer" and ask a clarifying question.
 
 ## Issue #${issue.iid}: ${issue.title}
 ${issue.description || "(no description)"}
-Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${accessBlock}${treeBlock}${previousBlock}${validationBlock}
+Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${accessBlock}${treeBlock}${rulesBlock}${previousBlock}${validationBlock}
 
 ## Relevant files (current state as of the proposed changes)
 ${filesBlock}