maxsimcli 4.6.0 → 4.7.1

package/dist/mcp-server.cjs

@@ -37,6 +37,8 @@ require("node:os");
 let node_buffer = require("node:buffer");
 let child_process = require("child_process");
 require("node:events");
+let node_child_process = require("node:child_process");
+let node_util = require("node:util");
 
 //#region ../../node_modules/zod/v3/helpers/util.js
 var util$2;
@@ -26769,17 +26771,12 @@ const isSummaryFile = (f) => f.endsWith("-SUMMARY.md") || f === "SUMMARY.md";
 const planId = (f) => f.replace("-PLAN.md", "").replace("PLAN.md", "");
 const summaryId = (f) => f.replace("-SUMMARY.md", "").replace("SUMMARY.md", "");
 /** List subdirectory names, optionally sorted by phase number. */
-function listSubDirs(dir, sortByPhase = false) {
-	const dirs = node_fs.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
-	return sortByPhase ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
-}
-/** Async version of listSubDirs using fs.promises. */
-async function listSubDirsAsync(dir, sortByPhase = false) {
+async function listSubDirs(dir, sortByPhase = false) {
 	const dirs = (await node_fs.promises.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
 	return sortByPhase ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
 }
-/** Async version of safeReadFile using fs.promises. */
-async function safeReadFileAsync(filePath) {
+/** Read a file, returning null if it doesn't exist or fails. */
+async function safeReadFile(filePath) {
 	try {
 		return await node_fs.promises.readFile(filePath, "utf-8");
 	} catch {
@@ -26800,15 +26797,65 @@ function debugLog(contextOrError, error) {
 function escapePhaseNum(phase) {
 	return String(phase).replace(/\./g, "\\.");
 }
-function safeReadFile(filePath) {
+let _configCache = null;
+function normalizePhaseName(phase) {
+	const match = phase.match(/^(\d+)([A-Z])?(\.\d+)?/i);
+	if (!match) return phase;
+	const padded = match[1].padStart(2, "0");
+	const letter = match[2] ? match[2].toUpperCase() : "";
+	const decimal = match[3] || "";
+	return padded + letter + decimal;
+}
+function comparePhaseNum(a, b) {
+	const pa = String(a).match(/^(\d+)([A-Z])?(\.\d+)?/i);
+	const pb = String(b).match(/^(\d+)([A-Z])?(\.\d+)?/i);
+	if (!pa || !pb) return String(a).localeCompare(String(b));
+	const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
+	if (intDiff !== 0) return intDiff;
+	const la = (pa[2] || "").toUpperCase();
+	const lb = (pb[2] || "").toUpperCase();
+	if (la !== lb) {
+		if (!la) return -1;
+		if (!lb) return 1;
+		return la < lb ? -1 : 1;
+	}
+	return (pa[3] ? parseFloat(pa[3]) : -1) - (pb[3] ? parseFloat(pb[3]) : -1);
+}
+/**
+* Returns the canonical regex for matching Phase heading lines in ROADMAP.md.
+*
+* General form (no escapedPhaseNum):
+*   Matches: ## Phase 03: Name Here
+*   Group 1: phase number string (e.g. "03", "3A", "2.1")
+*   Group 2: phase name string (e.g. "Name Here")
+*
+* Specific form (with escapedPhaseNum):
+*   Matches: ## Phase 03: Name Here
+*   Group 1: phase name string only
+*
+* @param escapedPhaseNum - regex-escaped phase number string to match a specific phase
+* @param flags - regex flags (default: 'gi')
+*/
+function getPhasePattern(escapedPhaseNum, flags = "gim") {
+	if (escapedPhaseNum) return new RegExp(`^#{2,4}\\s*Phase\\s+${escapedPhaseNum}:\\s*([^\\n]+)`, flags);
+	return new RegExp(`^#{2,4}\\s*Phase\\s+(\\d+[A-Z]?(?:\\.\\d+)?)\\s*:\\s*([^\\n]+)`, flags);
+}
+function generateSlugInternal(text) {
+	if (!text) return null;
+	return (0, import_slugify.default)(text, {
+		lower: true,
+		strict: true
+	});
+}
+async function pathExistsInternal(p) {
 	try {
-		return node_fs.default.readFileSync(filePath, "utf-8");
+		await node_fs.promises.access(p);
+		return true;
 	} catch {
-		return null;
+		return false;
 	}
 }
-let _configCache = null;
-function loadConfig(cwd) {
+async function loadConfig(cwd) {
 	if (_configCache && _configCache.cwd === cwd) return _configCache.config;
 	const cfgPath = configPath(cwd);
 	const defaults = {
@@ -26825,7 +26872,7 @@ function loadConfig(cwd) {
 		brave_search: false
 	};
 	try {
-		const raw = node_fs.default.readFileSync(cfgPath, "utf-8");
+		const raw = await node_fs.promises.readFile(cfgPath, "utf-8");
 		const parsed = JSON.parse(raw);
 		const get = (key, nested) => {
 			if (parsed[key] !== void 0) return parsed[key];
@@ -26887,7 +26934,7 @@ function loadConfig(cwd) {
 		};
 		return result;
 	} catch (e) {
-		if (node_fs.default.existsSync(cfgPath)) {
+		if (await pathExistsInternal(cfgPath)) {
 			console.warn(`[maxsim] Warning: config.json exists but could not be parsed — using defaults.`);
 			debugLog("config-load-failed", e);
 		}
@@ -26898,57 +26945,15 @@ function loadConfig(cwd) {
 		return defaults;
 	}
 }
-function normalizePhaseName(phase) {
-	const match = phase.match(/^(\d+)([A-Z])?(\.\d+)?/i);
-	if (!match) return phase;
-	const padded = match[1].padStart(2, "0");
-	const letter = match[2] ? match[2].toUpperCase() : "";
-	const decimal = match[3] || "";
-	return padded + letter + decimal;
-}
-function comparePhaseNum(a, b) {
-	const pa = String(a).match(/^(\d+)([A-Z])?(\.\d+)?/i);
-	const pb = String(b).match(/^(\d+)([A-Z])?(\.\d+)?/i);
-	if (!pa || !pb) return String(a).localeCompare(String(b));
-	const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
-	if (intDiff !== 0) return intDiff;
-	const la = (pa[2] || "").toUpperCase();
-	const lb = (pb[2] || "").toUpperCase();
-	if (la !== lb) {
-		if (!la) return -1;
-		if (!lb) return 1;
-		return la < lb ? -1 : 1;
-	}
-	return (pa[3] ? parseFloat(pa[3]) : -1) - (pb[3] ? parseFloat(pb[3]) : -1);
-}
-/**
-* Returns the canonical regex for matching Phase heading lines in ROADMAP.md.
-*
-* General form (no escapedPhaseNum):
-*   Matches: ## Phase 03: Name Here
-*   Group 1: phase number string (e.g. "03", "3A", "2.1")
-*   Group 2: phase name string (e.g. "Name Here")
-*
-* Specific form (with escapedPhaseNum):
-*   Matches: ## Phase 03: Name Here
-*   Group 1: phase name string only
-*
-* @param escapedPhaseNum - regex-escaped phase number string to match a specific phase
-* @param flags - regex flags (default: 'gi')
-*/
-function getPhasePattern(escapedPhaseNum, flags = "gim") {
-	if (escapedPhaseNum) return new RegExp(`^#{2,4}\\s*Phase\\s+${escapedPhaseNum}:\\s*([^\\n]+)`, flags);
-	return new RegExp(`^#{2,4}\\s*Phase\\s+(\\d+[A-Z]?(?:\\.\\d+)?)\\s*:\\s*([^\\n]+)`, flags);
-}
-function searchPhaseInDir(baseDir, relBase, normalized) {
+async function searchPhaseInDir(baseDir, relBase, normalized) {
 	try {
-		const match = listSubDirs(baseDir, true).find((d) => d.startsWith(normalized));
+		const match = (await listSubDirs(baseDir, true)).find((d) => d.startsWith(normalized));
 		if (!match) return null;
 		const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)?)-?(.*)/i);
 		const phaseNumber = dirMatch ? dirMatch[1] : normalized;
 		const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
 		const phaseDir = node_path.default.join(baseDir, match);
-		const phaseFiles = node_fs.default.readdirSync(phaseDir);
+		const phaseFiles = await node_fs.promises.readdir(phaseDir);
 		const plans = phaseFiles.filter(isPlanFile).sort();
 		const summaries = phaseFiles.filter(isSummaryFile).sort();
 		const hasResearch = phaseFiles.some((f) => f.endsWith("-RESEARCH.md") || f === "RESEARCH.md");
@@ -26970,7 +26975,7 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
 			has_verification: hasVerification
 		};
 	} catch (e) {
-		debugLog("search-phase-in-dir-failed", {
+		debugLog("search-phase-in-dir-async-failed", {
 			dir: baseDir,
 			phase: normalized,
 			error: errorMsg(e)
@@ -26978,148 +26983,82 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
 		return null;
 	}
 }
-function findPhaseInternal(cwd, phase) {
+async function findPhaseInternal(cwd, phase) {
 	if (!phase) return null;
 	const pd = phasesPath(cwd);
 	const normalized = normalizePhaseName(phase);
-	const current = searchPhaseInDir(pd, node_path.default.join(".planning", "phases"), normalized);
+	const current = await searchPhaseInDir(pd, node_path.default.join(".planning", "phases"), normalized);
 	if (current) return current;
-	const milestonesDir = planningPath(cwd, "milestones");
-	try {
-		node_fs.default.statSync(milestonesDir);
-	} catch {
-		return null;
+	const archiveDir = planningPath(cwd, "archive");
+	if (await pathExistsInternal(archiveDir)) try {
+		const versionDirs = (await node_fs.promises.readdir(archiveDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse();
+		for (const versionName of versionDirs) {
+			const result = await searchPhaseInDir(node_path.default.join(archiveDir, versionName), node_path.default.join(".planning", "archive", versionName), normalized);
+			if (result) {
+				result.archived = versionName;
+				return result;
+			}
+		}
+	} catch (e) {
+		debugLog("find-phase-async-archive-search-failed", e);
 	}
+	const milestonesDir = planningPath(cwd, "milestones");
+	if (!await pathExistsInternal(milestonesDir)) return null;
 	try {
-		const archiveDirs = node_fs.default.readdirSync(milestonesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name)).map((e) => e.name).sort().reverse();
+		const archiveDirs = (await node_fs.promises.readdir(milestonesDir, { withFileTypes: true })).filter((e) => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name)).map((e) => e.name).sort().reverse();
 		for (const archiveName of archiveDirs) {
 			const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
 			if (!versionMatch) continue;
 			const version = versionMatch[1];
-			const result = searchPhaseInDir(node_path.default.join(milestonesDir, archiveName), node_path.default.join(".planning", "milestones", archiveName), normalized);
+			const result = await searchPhaseInDir(node_path.default.join(milestonesDir, archiveName), node_path.default.join(".planning", "milestones", archiveName), normalized);
 			if (result) {
 				result.archived = version;
 				return result;
 			}
 		}
 	} catch (e) {
-		debugLog("find-phase-milestone-search-failed", e);
+		debugLog("find-phase-async-milestone-search-failed", e);
 	}
 	return null;
 }
-function getArchivedPhaseDirs(cwd) {
-	const milestonesDir = planningPath(cwd, "milestones");
+async function getArchivedPhaseDirs(cwd) {
 	const results = [];
+	const archiveDir = planningPath(cwd, "archive");
 	try {
-		const phaseDirs = node_fs.default.readdirSync(milestonesDir, { withFileTypes: true }).filter((e) => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name)).map((e) => e.name).sort().reverse();
-		for (const archiveName of phaseDirs) {
-			const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
-			if (!versionMatch) continue;
-			const version = versionMatch[1];
-			const archivePath = node_path.default.join(milestonesDir, archiveName);
-			const dirs = listSubDirs(archivePath, true);
+		const versionDirs = (await node_fs.promises.readdir(archiveDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse();
+		for (const versionName of versionDirs) {
+			const versionPath = node_path.default.join(archiveDir, versionName);
+			const dirs = await listSubDirs(versionPath, true);
 			for (const dir of dirs) results.push({
 				name: dir,
-				milestone: version,
-				basePath: node_path.default.join(".planning", "milestones", archiveName),
-				fullPath: node_path.default.join(archivePath, dir)
+				milestone: versionName,
+				basePath: node_path.default.join(".planning", "archive", versionName),
+				fullPath: node_path.default.join(versionPath, dir)
 			});
 		}
 	} catch (e) {
-		debugLog("get-archived-phase-dirs-failed", e);
-	}
-	return results;
-}
-function generateSlugInternal(text) {
-	if (!text) return null;
-	return (0, import_slugify.default)(text, {
-		lower: true,
-		strict: true
-	});
-}
-async function pathExistsAsync(p) {
-	try {
-		await node_fs.promises.access(p);
-		return true;
-	} catch {
-		return false;
-	}
-}
-async function searchPhaseInDirAsync(baseDir, relBase, normalized) {
-	try {
-		const match = (await listSubDirsAsync(baseDir, true)).find((d) => d.startsWith(normalized));
-		if (!match) return null;
-		const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)?)-?(.*)/i);
-		const phaseNumber = dirMatch ? dirMatch[1] : normalized;
-		const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
-		const phaseDir = node_path.default.join(baseDir, match);
-		const phaseFiles = await node_fs.promises.readdir(phaseDir);
-		const plans = phaseFiles.filter(isPlanFile).sort();
-		const summaries = phaseFiles.filter(isSummaryFile).sort();
-		const hasResearch = phaseFiles.some((f) => f.endsWith("-RESEARCH.md") || f === "RESEARCH.md");
-		const hasContext = phaseFiles.some((f) => f.endsWith("-CONTEXT.md") || f === "CONTEXT.md");
-		const hasVerification = phaseFiles.some((f) => f.endsWith("-VERIFICATION.md") || f === "VERIFICATION.md");
-		const completedPlanIds = new Set(summaries.map(summaryId));
-		const incompletePlans = plans.filter((p) => !completedPlanIds.has(planId(p)));
-		return {
-			found: true,
-			directory: node_path.default.join(relBase, match),
-			phase_number: phaseNumber,
-			phase_name: phaseName,
-			phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") : null,
-			plans,
-			summaries,
-			incomplete_plans: incompletePlans,
-			has_research: hasResearch,
-			has_context: hasContext,
-			has_verification: hasVerification
-		};
-	} catch (e) {
-		debugLog("search-phase-in-dir-async-failed", {
-			dir: baseDir,
-			phase: normalized,
-			error: errorMsg(e)
-		});
-		return null;
-	}
-}
-async function findPhaseInternalAsync(cwd, phase) {
-	if (!phase) return null;
-	const pd = phasesPath(cwd);
-	const normalized = normalizePhaseName(phase);
-	const current = await searchPhaseInDirAsync(pd, node_path.default.join(".planning", "phases"), normalized);
-	if (current) return current;
-	const archiveDir = planningPath(cwd, "archive");
-	if (await pathExistsAsync(archiveDir)) try {
-		const versionDirs = (await node_fs.promises.readdir(archiveDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse();
-		for (const versionName of versionDirs) {
-			const result = await searchPhaseInDirAsync(node_path.default.join(archiveDir, versionName), node_path.default.join(".planning", "archive", versionName), normalized);
-			if (result) {
-				result.archived = versionName;
-				return result;
-			}
-		}
-	} catch (e) {
-		debugLog("find-phase-async-archive-search-failed", e);
+		debugLog("get-archived-phase-dirs-async-archive-failed", e);
 	}
 	const milestonesDir = planningPath(cwd, "milestones");
-	if (!await pathExistsAsync(milestonesDir)) return null;
 	try {
-		const archiveDirs = (await node_fs.promises.readdir(milestonesDir, { withFileTypes: true })).filter((e) => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name)).map((e) => e.name).sort().reverse();
-		for (const archiveName of archiveDirs) {
+		const phaseDirs = (await node_fs.promises.readdir(milestonesDir, { withFileTypes: true })).filter((e) => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name)).map((e) => e.name).sort().reverse();
+		for (const archiveName of phaseDirs) {
 			const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
 			if (!versionMatch) continue;
 			const version = versionMatch[1];
-			const result = await searchPhaseInDirAsync(node_path.default.join(milestonesDir, archiveName), node_path.default.join(".planning", "milestones", archiveName), normalized);
-			if (result) {
-				result.archived = version;
-				return result;
-			}
+			const archiveMilestonePath = node_path.default.join(milestonesDir, archiveName);
+			const dirs = await listSubDirs(archiveMilestonePath, true);
+			for (const dir of dirs) results.push({
+				name: dir,
+				milestone: version,
+				basePath: node_path.default.join(".planning", "milestones", archiveName),
+				fullPath: node_path.default.join(archiveMilestonePath, dir)
+			});
 		}
 	} catch (e) {
-		debugLog("find-phase-async-milestone-search-failed", e);
+		debugLog("get-archived-phase-dirs-async-failed", e);
 	}
-	return null;
+	return results;
 }
 
 //#endregion
@@ -33860,7 +33799,7 @@ async function phaseInsertCore(cwd, afterPhase, description, options) {
 	const normalizedBase = normalizePhaseName(afterPhase);
 	const existingDecimals = [];
 	try {
-		const dirs = await listSubDirsAsync(phasesDirPath);
+		const dirs = await listSubDirs(phasesDirPath);
 		const decimalPattern = new RegExp(`^${normalizedBase}\\.(\\d+)`);
 		for (const dir of dirs) {
 			const dm = dir.match(decimalPattern);
@@ -33899,12 +33838,12 @@ async function phaseCompleteCore(cwd, phaseNum) {
 	const stPath = statePath(cwd);
 	const phasesDirPath = phasesPath(cwd);
 	const today = todayISO();
-	const phaseInfo = await findPhaseInternalAsync(cwd, phaseNum);
+	const phaseInfo = await findPhaseInternal(cwd, phaseNum);
 	if (!phaseInfo) throw new Error(`Phase ${phaseNum} not found`);
 	const planCount = phaseInfo.plans.length;
 	const summaryCount = phaseInfo.summaries.length;
 	let requirementsUpdated = false;
-	const rmExists = await pathExistsAsync(rmPath);
+	const rmExists = await pathExistsInternal(rmPath);
 	if (rmExists) {
 		let roadmapContent = await node_fs.promises.readFile(rmPath, "utf-8");
 		const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapePhaseNum(phaseNum)}[:\\s][^\\n]*)`, "i");
@@ -33918,7 +33857,7 @@ async function phaseCompleteCore(cwd, phaseNum) {
 		await node_fs.promises.writeFile(rmPath, roadmapContent, "utf-8");
 		debugLog("phase-complete-write", `ROADMAP.md updated for phase ${phaseNum}`);
 		const reqPath = planningPath(cwd, "REQUIREMENTS.md");
-		if (await pathExistsAsync(reqPath)) {
+		if (await pathExistsInternal(reqPath)) {
 			const reqMatch = roadmapContent.match(new RegExp(`Phase\\s+${escapePhaseNum(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, "i"));
 			if (reqMatch) {
 				const reqIds = reqMatch[1].replace(/[\[\]]/g, "").split(/[,\s]+/).map((r) => r.trim()).filter(Boolean);
@@ -33938,7 +33877,7 @@ async function phaseCompleteCore(cwd, phaseNum) {
 	let nextPhaseName = null;
 	let isLastPhase = true;
 	try {
-		const dirs = await listSubDirsAsync(phasesDirPath, true);
+		const dirs = await listSubDirs(phasesDirPath, true);
 		for (const dir of dirs) {
 			const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)?)-?(.*)/i);
 			if (dm) {
@@ -33953,7 +33892,7 @@ async function phaseCompleteCore(cwd, phaseNum) {
 	} catch (e) {
 		debugLog("phase-complete-next-phase-scan-failed", e);
 	}
-	const stExists = await pathExistsAsync(stPath);
+	const stExists = await pathExistsInternal(stPath);
 	if (stExists) {
 		let stateContent = await node_fs.promises.readFile(stPath, "utf-8");
 		stateContent = stateContent.replace(/(\*\*Current Phase:\*\*\s*).*/, `$1${nextPhaseNum || phaseNum}`);
@@ -33980,6 +33919,1462 @@ async function phaseCompleteCore(cwd, phaseNum) {
 	};
 }
 
+//#endregion
+//#region src/github/gh.ts
+/**
+* GitHub CLI Wrapper — Core gh CLI interaction layer
+*
+* Wraps the `gh` CLI using `child_process.execFile` (never `exec`) for security.
+* Provides typed results via GhResult<T> discriminated union.
+* Supports graceful degradation: detectGitHubMode() returns 'local-only'
+* when gh is not installed or not authenticated with required scopes.
+*
+* CRITICAL: Never import octokit or any npm GitHub SDK.
+* CRITICAL: Never call process.exit() — return GhResult instead.
+*/
+const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
+/**
+* Check if the `gh` CLI is installed and authenticated with required scopes.
+*
+* Parses the output of `gh auth status` (which writes to stderr, not stdout).
+* Returns structured AuthStatus with scope detection for 'project' scope.
+* Timeout: 10 seconds.
+*/
+async function checkGhAuth() {
+	try {
+		const { stdout, stderr } = await execFileAsync("gh", ["auth", "status"], { timeout: 1e4 });
+		const output = stderr || stdout;
+		const authenticated = !output.includes("not logged in");
+		const scopeMatch = output.match(/Token scopes?:\s*'([^']+(?:',\s*'[^']+)*)'/);
+		const scopes = [];
+		if (scopeMatch) {
+			const allScopes = scopeMatch[0].matchAll(/'([^']+)'/g);
+			for (const m of allScopes) scopes.push(m[1]);
+		}
+		const userMatch = output.match(/Logged in to [^\s]+ as ([^\s(]+)/);
+		return {
+			installed: true,
+			authenticated,
+			scopes,
+			hasProjectScope: scopes.includes("project") || scopes.includes("read:project"),
+			username: userMatch ? userMatch[1] : null
+		};
+	} catch (e) {
+		const error = e;
+		if (error.code === "ENOENT") return {
+			installed: false,
+			authenticated: false,
+			scopes: [],
+			hasProjectScope: false,
+			username: null
+		};
+		error.stderr || error.message;
+		return {
+			installed: true,
+			authenticated: false,
+			scopes: [],
+			hasProjectScope: false,
+			username: null
+		};
+	}
+}
+/**
+* Detect the GitHub integration mode based on auth status.
+*
+* Returns 'full' only when gh is installed, authenticated, and has the
+* 'project' scope. Otherwise returns 'local-only' for graceful degradation.
+*/
+async function detectGitHubMode() {
+	const auth = await checkGhAuth();
+	if (!auth.installed) return "local-only";
+	if (!auth.authenticated) return "local-only";
+	if (!auth.hasProjectScope) {
+		console.error("[maxsim] GitHub Projects requires 'project' scope. Run: gh auth refresh -s project");
+		return "local-only";
+	}
+	return "full";
+}
+/**
+* Execute a `gh` CLI command and return a typed GhResult.
+*
+* - Uses `execFile` (not `exec`) for security
+* - Default timeout: 30 seconds
+* - Auto-detects JSON output when args contain `--json` or `--format`
+* - Maps exit codes and stderr patterns to GhErrorCode
+* - For `gh issue create`: does NOT try to parse JSON (it returns a URL string)
+* - Always includes raw stderr in error messages for AI consumption
+*/
+async function ghExec(args, options) {
+	const timeout = options?.timeout ?? 3e4;
+	const isIssueCreate = args[0] === "issue" && args[1] === "create";
+	const hasJsonFlag = args.includes("--json") || args.some((a) => a.startsWith("--format"));
+	const shouldParseJson = options?.parseJson ?? (hasJsonFlag && !isIssueCreate);
+	try {
+		const { stdout, stderr } = await execFileAsync("gh", args, {
+			cwd: options?.cwd,
+			timeout,
+			maxBuffer: 10 * 1024 * 1024
+		});
+		if (shouldParseJson) try {
+			return {
+				ok: true,
+				data: JSON.parse(stdout)
+			};
+		} catch {
+			return {
+				ok: false,
+				error: `Failed to parse gh output as JSON: ${stdout.slice(0, 500)}`,
+				code: "UNKNOWN"
+			};
+		}
+		return {
+			ok: true,
+			data: stdout.trim()
+		};
+	} catch (e) {
+		return mapExecError(e);
+	}
+}
+/**
+* Execute a GraphQL query via `gh api graphql`.
+*
+* - String variables use `-f key=value`
+* - Non-string variables (numbers, booleans) use `-F key=value`
+* - Parses JSON response and checks for GraphQL `errors` array
+*/
+async function ghGraphQL(query, variables) {
+	const args = [
+		"api",
+		"graphql",
+		"-f",
+		`query=${query}`
+	];
+	if (variables) for (const [key, value] of Object.entries(variables)) if (typeof value === "string") args.push("-f", `${key}=${value}`);
+	else args.push("-F", `${key}=${String(value)}`);
+	const result = await ghExec(args, { parseJson: true });
+	if (!result.ok) return result;
+	if (result.data.errors && result.data.errors.length > 0) {
+		const messages = result.data.errors.map((e) => e.message).join("; ");
+		const code = mapGraphQLErrorCode(messages);
+		return {
+			ok: false,
+			error: `GraphQL error: ${messages}`,
+			code
+		};
+	}
+	if (result.data.data === void 0) return {
+		ok: false,
+		error: "GraphQL response missing data field",
+		code: "UNKNOWN"
+	};
+	return {
+		ok: true,
+		data: result.data.data
+	};
+}
+/**
+* Map an execFile error to a GhResult with appropriate GhErrorCode.
+*/
+function mapExecError(e) {
+	const error = e;
+	if (error.code === "ENOENT") return {
+		ok: false,
+		error: "gh CLI is not installed. Install from https://cli.github.com/",
+		code: "NOT_INSTALLED"
+	};
+	const stderr = error.stderr || error.message || "";
+	if (error.status === 4) return {
+		ok: false,
+		error: `Not found: ${stderr}`,
+		code: "NOT_FOUND"
+	};
+	if (stderr.includes("not logged in") || stderr.includes("authentication") || stderr.includes("auth login") || stderr.includes("401")) return {
+		ok: false,
+		error: `Authentication required: ${stderr}`,
+		code: "NOT_AUTHENTICATED"
+	};
+	if (stderr.includes("403") || stderr.includes("permission") || stderr.includes("denied")) return {
+		ok: false,
+		error: `Permission denied: ${stderr}`,
+		code: "PERMISSION_DENIED"
+	};
+	if (stderr.includes("rate limit") || stderr.includes("429") || stderr.includes("API rate")) return {
+		ok: false,
+		error: `Rate limited: ${stderr}`,
+		code: "RATE_LIMITED"
+	};
+	if (stderr.includes("scope") || stderr.includes("insufficient")) return {
+		ok: false,
+		error: `Missing scope: ${stderr}`,
+		code: "SCOPE_MISSING"
+	};
+	if (stderr.includes("not found") || stderr.includes("404") || stderr.includes("Could not resolve")) return {
+		ok: false,
+		error: `Not found: ${stderr}`,
+		code: "NOT_FOUND"
+	};
+	return {
+		ok: false,
+		error: `gh command failed: ${stderr}`,
+		code: "UNKNOWN"
+	};
+}
+/**
+* Map GraphQL error messages to GhErrorCode.
+*/
+function mapGraphQLErrorCode(message) {
+	const lower = message.toLowerCase();
+	if (lower.includes("not found") || lower.includes("could not resolve")) return "NOT_FOUND";
+	if (lower.includes("insufficient") || lower.includes("scope")) return "SCOPE_MISSING";
+	if (lower.includes("forbidden") || lower.includes("permission")) return "PERMISSION_DENIED";
+	if (lower.includes("rate") || lower.includes("throttl")) return "RATE_LIMITED";
+	return "UNKNOWN";
+}
+
+//#endregion
+//#region src/github/mapping.ts
+/**
+* GitHub Issues Mapping — Persistence layer for github-issues.json
+*
+* Manages the `.planning/github-issues.json` file that maps MAXSIM tasks/todos
+* to their corresponding GitHub issue numbers, node IDs, and project item IDs.
+*
+* All file operations use synchronous fs (matching the pattern in existing core modules).
+* Uses planningPath() from core to construct file paths.
+*
+* CRITICAL: Never call process.exit() — throw or return null instead.
+*/
+const MAPPING_FILENAME = "github-issues.json";
+/**
+* Get the absolute path to `.planning/github-issues.json` for a given cwd.
+*/
+function mappingFilePath(cwd) {
+	return planningPath(cwd, MAPPING_FILENAME);
+}
+/**
+* Load and parse the mapping file.
+*
+* Returns null if the file does not exist.
+* Throws on malformed JSON or invalid structure (missing required fields).
+*/
+function loadMapping(cwd) {
+	const filePath = mappingFilePath(cwd);
+	try {
+		node_fs.default.statSync(filePath);
+	} catch {
+		return null;
+	}
+	const raw = node_fs.default.readFileSync(filePath, "utf-8");
+	const parsed = JSON.parse(raw);
+	if (typeof parsed.project_number !== "number" || typeof parsed.repo !== "string") throw new Error(`Invalid github-issues.json: missing required fields 'project_number' (number) and 'repo' (string)`);
+	return parsed;
+}
+/**
+* Write the mapping file to `.planning/github-issues.json`.
+*
+* Creates the `.planning/` directory if it does not exist.
+* Writes with 2-space indent for readability and diff-friendliness.
+*/
+function saveMapping(cwd, mapping) {
+	const filePath = mappingFilePath(cwd);
+	const dir = node_path.default.dirname(filePath);
+	node_fs.default.mkdirSync(dir, { recursive: true });
+	node_fs.default.writeFileSync(filePath, JSON.stringify(mapping, null, 2) + "\n", "utf-8");
+}
+/**
+* Update a specific task's issue mapping within a phase.
+*
+* Load-modify-save pattern. Creates phase entry if it does not exist.
+* Merges partial data with existing entry (if any).
+*
+* @throws If mapping file does not exist (must be initialized first via saveMapping)
+*/
+function updateTaskMapping(cwd, phaseNum, taskId, data) {
+	const mapping = loadMapping(cwd);
+	if (!mapping) throw new Error("github-issues.json does not exist. Run project setup first.");
+	if (!mapping.phases[phaseNum]) mapping.phases[phaseNum] = {
+		tracking_issue: {
+			number: 0,
+			node_id: "",
+			item_id: "",
+			status: "To Do"
+		},
+		plan: "",
+		tasks: {}
+	};
+	const existing = mapping.phases[phaseNum].tasks[taskId];
+	const defaults = {
+		number: 0,
+		node_id: "",
+		item_id: "",
+		status: "To Do"
+	};
+	mapping.phases[phaseNum].tasks[taskId] = Object.assign(defaults, existing, data);
+	saveMapping(cwd, mapping);
+}
+/**
+* Update a specific todo's issue mapping.
+*
+* Load-modify-save pattern. Creates `todos` section if missing.
+* Merges partial data with existing entry (if any).
+*
+* @throws If mapping file does not exist (must be initialized first via saveMapping)
+*/
+function updateTodoMapping(cwd, todoId, data) {
+	const mapping = loadMapping(cwd);
+	if (!mapping) throw new Error("github-issues.json does not exist. Run project setup first.");
+	if (!mapping.todos) mapping.todos = {};
+	const existing = mapping.todos[todoId];
+	const defaults = {
+		number: 0,
+		node_id: "",
+		item_id: "",
+		status: "To Do"
+	};
+	mapping.todos[todoId] = Object.assign(defaults, existing, data);
+	saveMapping(cwd, mapping);
+}
+/**
+* Create a properly typed empty mapping object with sensible defaults.
+*
+* Used during initial project setup to create the mapping file.
+*/
+function createEmptyMapping(repo) {
+	return {
+		project_number: 0,
+		project_id: "",
+		repo,
+		status_field_id: "",
+		status_options: {},
+		estimate_field_id: "",
+		milestone_id: 0,
+		milestone_title: "",
+		labels: {},
+		phases: {},
+		todos: {}
+	};
+}
+
+//#endregion
+//#region src/github/issues.ts
+/**
+* Parse an issue number from a `gh issue create` stdout URL.
+*
+* `gh issue create` outputs a URL like:
+*   https://github.com/owner/repo/issues/42\n
+*
+* We trim whitespace and extract the last path segment as the issue number.
+*/
+function parseIssueNumberFromUrl(stdout) {
+	const lastSegment = stdout.trim().split("/").pop();
+	if (!lastSegment) return null;
+	const num = parseInt(lastSegment, 10);
+	return Number.isNaN(num) ? null : num;
+}
+/**
+* After creating an issue (parsed number from URL), fetch its node_id
+* via `gh issue view {number} --json nodeId,number,url`.
+*/
+async function fetchIssueDetails(issueNumber) {
+	const result = await ghExec([
+		"issue",
+		"view",
+		String(issueNumber),
+		"--json",
+		"nodeId,number,url"
+	], { parseJson: true });
+	if (!result.ok) return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+	return {
+		ok: true,
+		data: {
+			number: result.data.number,
+			url: result.data.url,
+			node_id: result.data.nodeId
+		}
+	};
+}
+/**
+* Create a task issue with full specification body in collapsible details section.
+*
+* Title format: `[P{phaseNum}] {title}`
+* Body includes summary, actions, acceptance criteria, dependencies in `<details>`.
+* Labels: maxsim, phase-task.
+*
+* Returns the issue number, URL, and node_id.
+*/
+async function createTaskIssue(opts) {
+	const issueTitle = `[P${opts.phaseNum}] ${opts.title}`;
+	const depsSection = opts.dependencies && opts.dependencies.length > 0 ? `\n### Dependencies\nDepends on: ${opts.dependencies.map((d) => `#${d}`).join(", ")}\n` : "";
+	const estimateSection = opts.estimate !== void 0 ? `\n### Estimate\n${opts.estimate} points\n` : "";
+	const args = [
+		"issue",
+		"create",
+		"--title",
+		issueTitle,
+		"--body",
+		`## Summary
+${opts.summary}
+
+<details>
+<summary>Full Specification</summary>
+
+### Actions
+${opts.actions.map((a) => `- ${a}`).join("\n")}
+
+### Acceptance Criteria
+${opts.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n")}
+${depsSection}${estimateSection}
+</details>
+
+---
+*Phase: ${opts.phaseNum} | Plan: ${opts.planNum} | Task: ${opts.taskId}*
+*Generated by MAXSIM*`
+	];
+	args.push("--label", "maxsim");
+	args.push("--label", "phase-task");
+	if (opts.labels) for (const label of opts.labels) args.push("--label", label);
+	if (opts.milestone) args.push("--milestone", opts.milestone);
+	if (opts.projectTitle) args.push("--project", opts.projectTitle);
+	const createResult = await ghExec(args);
+	if (!createResult.ok) return {
+		ok: false,
+		error: createResult.error,
+		code: createResult.code
+	};
+	const issueNumber = parseIssueNumberFromUrl(createResult.data);
+	if (issueNumber === null) return {
+		ok: false,
+		error: `Failed to parse issue number from gh output: ${createResult.data}`,
+		code: "UNKNOWN"
+	};
+	return fetchIssueDetails(issueNumber);
+}
+/**
+* Create a parent tracking issue for a phase with a live checkbox task list.
+*
+* Title format: `[Phase {phaseNum}] {phaseName}`
+* Body includes task list with checkbox links: `- [ ] #{childNumber}`
+* Labels: maxsim, phase-task.
+*/
+async function createParentTrackingIssue(opts) {
+	const issueTitle = `[Phase ${opts.phaseNum}] ${opts.phaseName}`;
+	const taskList = opts.childIssueNumbers.map((n) => `- [ ] #${n}`).join("\n");
+	const args = [
+		"issue",
+		"create",
+		"--title",
+		issueTitle,
+		"--body",
+		`## Phase ${opts.phaseNum}: ${opts.phaseName}
+
+### Tasks
+${taskList}
+
+---
+*Phase tracking issue -- Generated by MAXSIM*`
+	];
+	args.push("--label", "maxsim");
+	args.push("--label", "phase-task");
+	if (opts.milestone) args.push("--milestone", opts.milestone);
+	if (opts.projectTitle) args.push("--project", opts.projectTitle);
+	const createResult = await ghExec(args);
+	if (!createResult.ok) return {
+		ok: false,
+		error: createResult.error,
+		code: createResult.code
+	};
+	const issueNumber = parseIssueNumberFromUrl(createResult.data);
+	if (issueNumber === null) return {
+		ok: false,
+		error: `Failed to parse issue number from gh output: ${createResult.data}`,
+		code: "UNKNOWN"
+	};
+	return fetchIssueDetails(issueNumber);
+}
+/**
+* Create a todo issue with a lighter body (no collapsible details section).
+*
+* Labels: maxsim, todo.
+*/
+async function createTodoIssue(opts) {
+	let body = "";
+	if (opts.description) body += `${opts.description}\n`;
+	if (opts.acceptanceCriteria && opts.acceptanceCriteria.length > 0) {
+		body += `\n### Acceptance Criteria\n`;
+		body += opts.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n");
+		body += "\n";
+	}
+	body += `\n---\n*Generated by MAXSIM*`;
+	const args = [
+		"issue",
+		"create",
+		"--title",
+		opts.title,
+		"--body",
+		body
+	];
+	args.push("--label", "maxsim");
+	args.push("--label", "todo");
+	if (opts.milestone) args.push("--milestone", opts.milestone);
+	if (opts.projectTitle) args.push("--project", opts.projectTitle);
+	const createResult = await ghExec(args);
+	if (!createResult.ok) return {
+		ok: false,
+		error: createResult.error,
+		code: createResult.code
+	};
+	const issueNumber = parseIssueNumberFromUrl(createResult.data);
+	if (issueNumber === null) return {
+		ok: false,
+		error: `Failed to parse issue number from gh output: ${createResult.data}`,
+		code: "UNKNOWN"
+	};
+	return fetchIssueDetails(issueNumber);
+}
+/**
+* Build a PR description body with `Closes #{N}` lines for auto-close on merge (AC-08).
+*
+* This function is called by `mcp_create_pr` in Plan 04's github-tools.ts.
+*/
+function buildPrBody(closesIssues, additionalContent) {
+	return `${closesIssues.map((n) => `Closes #${n}`).join("\n")}${additionalContent ? `\n\n${additionalContent}` : ""}`;
+}
+/**
+* Close an issue with an optional reason.
+*
+* Reason defaults to 'completed' if not specified.
+*/
+async function closeIssue(issueNumber, reason) {
+	const args = [
+		"issue",
+		"close",
+		String(issueNumber)
+	];
+	if (reason) args.push("--reason", reason);
+	const result = await ghExec(args);
+	if (!result.ok) return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Close an issue as superseded by a newer issue.
+*
+* 1. Posts "Superseded by #{newIssueNumber}" comment on old issue
+* 2. Adds 'superseded' label to old issue
+* 3. Closes old issue as completed
+* 4. Posts "Replaces #{oldIssueNumber}" comment on new issue
+*
+* Creates bidirectional cross-references.
+*/
+async function closeIssueAsSuperseded(oldIssueNumber, newIssueNumber) {
+	const commentResult = await postComment(oldIssueNumber, `Superseded by #${newIssueNumber}`);
+	if (!commentResult.ok) return {
+		ok: false,
+		error: commentResult.error,
+		code: commentResult.code
+	};
+	const labelResult = await ghExec([
+		"issue",
+		"edit",
+		String(oldIssueNumber),
+		"--add-label",
+		"superseded"
+	]);
+	if (!labelResult.ok) return {
+		ok: false,
+		error: labelResult.error,
+		code: labelResult.code
+	};
+	const closeResult = await closeIssue(oldIssueNumber, "completed");
+	if (!closeResult.ok) return closeResult;
+	const replaceCommentResult = await postComment(newIssueNumber, `Replaces #${oldIssueNumber}`);
+	if (!replaceCommentResult.ok) return {
+		ok: false,
+		error: replaceCommentResult.error,
+		code: replaceCommentResult.code
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Post a comment on an issue.
+*/
+async function postComment(issueNumber, body) {
+	const result = await ghExec([
+		"issue",
+		"comment",
+		String(issueNumber),
+		"--body",
+		body
+	]);
+	if (!result.ok) return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Import an existing external GitHub issue into MAXSIM tracking.
+*
+* Reads the issue details and adds 'maxsim' and 'imported' labels.
+* Returns the issue details for the AI to decide placement.
+*/
+async function importExternalIssue(issueNumber) {
+	const viewResult = await ghExec([
+		"issue",
+		"view",
+		String(issueNumber),
+		"--json",
+		"title,labels,body,state"
+	], { parseJson: true });
+	if (!viewResult.ok) return {
+		ok: false,
+		error: viewResult.error,
+		code: viewResult.code
+	};
+	const labelResult = await ghExec([
+		"issue",
+		"edit",
+		String(issueNumber),
+		"--add-label",
+		"maxsim,imported"
+	]);
+	if (!labelResult.ok) return {
+		ok: false,
+		error: labelResult.error,
+		code: labelResult.code
+	};
+	const existingLabels = viewResult.data.labels.map((l) => l.name);
+	const allLabels = Array.from(new Set([
+		...existingLabels,
+		"maxsim",
+		"imported"
+	]));
+	return {
+		ok: true,
+		data: {
+			number: issueNumber,
+			title: viewResult.data.title,
+			labels: allLabels
+		}
+	};
+}
+/**
+* Update the parent tracking issue's task list checkbox.
+*
+* Reads the parent issue body, finds `- [ ] #{childNumber}` or `- [x] #{childNumber}`,
+* toggles the checkbox, and updates the issue body via `gh issue edit`.
+*/
+async function updateParentTaskList(parentIssueNumber, childIssueNumber, checked) {
+	const viewResult = await ghExec([
+		"issue",
+		"view",
+		String(parentIssueNumber),
+		"--json",
+		"body"
+	], { parseJson: true });
+	if (!viewResult.ok) return {
+		ok: false,
+		error: viewResult.error,
+		code: viewResult.code
+	};
+	const currentBody = viewResult.data.body;
+	const checkboxPattern = new RegExp(`- \\[([ x])\\] #${childIssueNumber}\\b`, "g");
+	const newCheckState = checked ? "x" : " ";
+	const updatedBody = currentBody.replace(checkboxPattern, `- [${newCheckState}] #${childIssueNumber}`);
+	if (updatedBody === currentBody) return {
+		ok: true,
+		data: void 0
+	};
+	const editResult = await ghExec([
+		"issue",
+		"edit",
+		String(parentIssueNumber),
+		"--body",
+		updatedBody
+	]);
+	if (!editResult.ok) return {
+		ok: false,
+		error: editResult.error,
+		code: editResult.code
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Create all issues for a plan at once (eager creation on plan finalization).
+*
+* 1. Creates all task issues with concurrency limit of 5 (rate limit safety).
+* 2. After all task issues created, creates parent tracking issue.
+* 3. Updates mapping file for all created issues.
+* 4. Returns parent issue number and all task issue numbers.
+*
+* Handles partial failures: continues batch, reports which failed.
+*/
+async function createAllPlanIssues(opts) {
+	const BATCH_SIZE = 5;
+	const results = [];
+	const failures = [];
+	for (let i = 0; i < opts.tasks.length; i += BATCH_SIZE) {
+		const batchPromises = opts.tasks.slice(i, i + BATCH_SIZE).map(async (task) => {
+			let depIssueNumbers;
+			if (task.dependencies && task.dependencies.length > 0) depIssueNumbers = task.dependencies.map((depId) => {
+				const found = results.find((r) => r.taskId === depId);
+				return found ? found.issueNumber : 0;
+			}).filter((n) => n > 0);
+			const result = await createTaskIssue({
+				title: task.title,
+				phaseNum: opts.phaseNum,
+				planNum: opts.planNum,
+				taskId: task.taskId,
+				summary: task.summary,
+				actions: task.actions,
+				acceptanceCriteria: task.acceptanceCriteria,
+				dependencies: depIssueNumbers,
+				milestone: opts.milestone,
+				projectTitle: opts.projectTitle,
+				estimate: task.estimate
+			});
+			return {
+				taskId: task.taskId,
+				result
+			};
+		});
+		const batchResults = await Promise.all(batchPromises);
+		for (const { taskId, result } of batchResults) if (result.ok) results.push({
+			taskId,
+			issueNumber: result.data.number,
+			nodeId: result.data.node_id
+		});
+		else failures.push({
+			taskId,
+			error: result.error
+		});
+	}
+	if (results.length === 0) return {
+		ok: false,
+		error: `All task issue creations failed: ${failures.map((f) => `${f.taskId}: ${f.error}`).join("; ")}`,
+		code: "UNKNOWN"
+	};
+	const childNumbers = results.map((r) => r.issueNumber);
+	const parentResult = await createParentTrackingIssue({
+		phaseNum: opts.phaseNum,
+		phaseName: opts.phaseName,
+		childIssueNumbers: childNumbers,
+		milestone: opts.milestone,
+		projectTitle: opts.projectTitle
+	});
+	if (!parentResult.ok) return {
+		ok: false,
+		error: `Task issues created but parent tracking issue failed: ${parentResult.error}`,
+		code: parentResult.code
+	};
+	const mapping = loadMapping(opts.cwd);
+	if (mapping) {
+		if (!mapping.phases[opts.phaseNum]) mapping.phases[opts.phaseNum] = {
+			tracking_issue: {
+				number: 0,
+				node_id: "",
+				item_id: "",
+				status: "To Do"
+			},
+			plan: "",
+			tasks: {}
+		};
+		mapping.phases[opts.phaseNum].tracking_issue = {
+			number: parentResult.data.number,
+			node_id: parentResult.data.node_id,
+			item_id: "",
+			status: "To Do"
+		};
+		mapping.phases[opts.phaseNum].plan = `${opts.phaseNum}-${opts.planNum}`;
+		for (const r of results) mapping.phases[opts.phaseNum].tasks[r.taskId] = {
+			number: r.issueNumber,
+			node_id: r.nodeId,
+			item_id: "",
+			status: "To Do"
+		};
+		saveMapping(opts.cwd, mapping);
+	}
+	const taskIssues = results.map((r) => ({
+		taskId: r.taskId,
+		issueNumber: r.issueNumber
+	}));
+	return {
+		ok: true,
+		data: {
+			parentIssue: parentResult.data.number,
+			taskIssues
+		}
+	};
+}
+/**
+* Supersede old plan's issues when a plan is re-planned (fresh issues per plan).
+*
+* 1. Load mapping to find old plan's issue numbers.
+* 2. For each old issue, close as superseded with cross-reference to new issue.
+* 3. Close old parent tracking issue as superseded.
+* 4. Update mapping: mark old entries, add new entries.
+*/
+async function supersedePlanIssues(opts) {
+	const mapping = loadMapping(opts.cwd);
+	if (!mapping) return {
+		ok: false,
+		error: "github-issues.json does not exist. Run project setup first.",
+		code: "NOT_FOUND"
+	};
+	const phase = mapping.phases[opts.phaseNum];
+	if (!phase) return {
+		ok: false,
+		error: `No phase ${opts.phaseNum} found in mapping file`,
+		code: "NOT_FOUND"
+	};
+	const currentPlan = phase.plan;
+	const expectedOldPlan = `${opts.phaseNum}-${opts.oldPlanNum}`;
+	if (currentPlan !== expectedOldPlan) return {
+		ok: false,
+		error: `Phase ${opts.phaseNum} is on plan '${currentPlan}', expected '${expectedOldPlan}'`,
+		code: "UNKNOWN"
+	};
+	const failures = [];
+	const oldTasks = Object.entries(phase.tasks);
+	for (const [taskId, oldTask] of oldTasks) {
+		const newIssue = opts.newIssueNumbers.find((n) => n.taskId === taskId);
+		if (!newIssue) {
+			const closeResult = await closeIssue(oldTask.number, "completed");
+			if (!closeResult.ok) failures.push(`close task ${taskId} (#${oldTask.number}): ${closeResult.error}`);
+			continue;
+		}
+		const supersedeResult = await closeIssueAsSuperseded(oldTask.number, newIssue.issueNumber);
+		if (!supersedeResult.ok) failures.push(`supersede task ${taskId} (#${oldTask.number} -> #${newIssue.issueNumber}): ${supersedeResult.error}`);
+	}
+	if (phase.tracking_issue.number > 0) {
+		const closeResult = await closeIssue(phase.tracking_issue.number, "completed");
+		if (!closeResult.ok) failures.push(`close parent tracking issue #${phase.tracking_issue.number}: ${closeResult.error}`);
+	}
+	phase.plan = `${opts.phaseNum}-${opts.newPlanNum}`;
+	phase.tasks = {};
+	for (const newIssue of opts.newIssueNumbers) phase.tasks[newIssue.taskId] = {
+		number: newIssue.issueNumber,
+		node_id: "",
+		item_id: "",
+		status: "To Do"
+	};
+	saveMapping(opts.cwd, mapping);
+	if (failures.length > 0) return {
+		ok: false,
+		error: `Partial failure during supersession: ${failures.join("; ")}`,
+		code: "UNKNOWN"
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+
+//#endregion
+//#region src/github/projects.ts
+/**
+* Extract error info from a failed GhResult and re-wrap it for a different
+* generic type. This avoids TypeScript narrowing issues with discriminated
+* union property access.
+*/
+function fail$2(result) {
+	return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+}
+/**
+* Create a new GitHub Projects v2 board.
+*
+* Runs `gh project create --owner @me --title "{title}" --format json`.
+* Returns the project number and node ID.
+*/
+async function createProjectBoard(title) {
+	const result = await ghExec([
+		"project",
+		"create",
+		"--owner",
+		"@me",
+		"--title",
+		title,
+		"--format",
+		"json"
+	], { parseJson: true });
+	if (!result.ok) return result;
+	return {
+		ok: true,
+		data: {
+			number: result.data.number,
+			id: result.data.id
+		}
+	};
+}
+/**
+* Ensure a project board exists, creating it if needed.
+*
+* Checks the mapping file for an existing project. If found, verifies it
+* still exists via `gh project view`. If not found, creates a new board
+* and sets up fields and status options.
+*
+* Returns the project number, ID, and whether it was newly created.
+*/
+async function ensureProjectBoard(title, cwd) {
+	const mapping = loadMapping(cwd);
+	if (mapping && mapping.project_number > 0 && mapping.project_id) {
+		if ((await ghExec([
+			"project",
+			"view",
+			String(mapping.project_number),
+			"--owner",
+			"@me",
+			"--format",
+			"json"
+		], { parseJson: true })).ok) return {
+			ok: true,
+			data: {
+				number: mapping.project_number,
+				id: mapping.project_id,
+				created: false
+			}
+		};
+	}
+	const createResult = await createProjectBoard(title);
+	if (!createResult.ok) return fail$2(createResult);
+	const { number, id } = createResult.data;
+	const setupResult = await setupProjectFields(number, id, cwd);
+	if (!setupResult.ok) return fail$2(setupResult);
+	return {
+		ok: true,
+		data: {
+			number,
+			id,
+			created: true
+		}
+	};
+}
+/**
+* Get all fields for a project board.
+*
+* Runs `gh project field-list {num} --owner @me --format json`.
+* Returns field list with IDs, names, types, and options (for single-select).
+*/
+async function getProjectFields(projectNum) {
+	const result = await ghExec([
+		"project",
+		"field-list",
+		String(projectNum),
+		"--owner",
+		"@me",
+		"--format",
+		"json"
+	], { parseJson: true });
+	if (!result.ok) return fail$2(result);
+	return {
+		ok: true,
+		data: result.data.fields ?? result.data
+	};
+}
+/**
+* Add a new single-select option to a project field via GraphQL.
+*
+* The `updateProjectV2Field` mutation REPLACES all options, so all existing
+* options must be included alongside the new one.
+*
+* Returns the new option's ID.
+*/
+async function addStatusOption(projectId, statusFieldId, optionName, existingOptions) {
+	const result = await ghGraphQL(`
+    mutation {
+      updateProjectV2Field(input: {
+        projectId: "${projectId}"
+        fieldId: "${statusFieldId}"
+        singleSelectOptions: [${[...existingOptions.map((o) => `{name: "${o.name}", description: "", color: GRAY}`), `{name: "${optionName}", description: "", color: BLUE}`].join(", ")}]
+      }) {
+        projectV2Field {
+          ... on ProjectV2SingleSelectField {
+            options { id name }
+          }
+        }
+      }
+    }
+  `);
+	if (!result.ok) return fail$2(result);
+	const newOption = result.data.updateProjectV2Field.projectV2Field.options.find((o) => o.name === optionName);
+	if (!newOption) return {
+		ok: false,
+		error: `Option "${optionName}" was not found after mutation — it may have been renamed or rejected`,
+		code: "UNKNOWN"
+	};
+	return {
+		ok: true,
+		data: newOption.id
+	};
+}
+/**
+* Set up project fields: Status options and Estimate number field.
+*
+* Orchestrates the full field setup:
+* (a) Get existing fields
+* (b) Find Status field, verify "In Review" option exists or add it
+* (c) Create Estimate NUMBER field via `gh project field-create`
+* (d) Store all field/option IDs in the mapping file
+*/
+async function setupProjectFields(projectNum, projectId, cwd) {
+	const fieldsResult = await getProjectFields(projectNum);
+	if (!fieldsResult.ok) return fail$2(fieldsResult);
+	const fields = fieldsResult.data;
+	const statusField = fields.find((f) => f.name === "Status" && (f.type === "SINGLE_SELECT" || f.type === "ProjectV2SingleSelectField"));
+	if (!statusField) return {
+		ok: false,
+		error: "Status field not found on project board. This is unexpected for a Projects v2 board.",
+		code: "NOT_FOUND"
+	};
+	const statusOptions = statusField.options ?? [];
+	const statusOptionsMap = {};
+	for (const opt of statusOptions) statusOptionsMap[opt.name] = opt.id;
+	if (!statusOptionsMap["In Review"]) {
+		const addResult = await addStatusOption(projectId, statusField.id, "In Review", statusOptions);
+		if (!addResult.ok) return fail$2(addResult);
+		statusOptionsMap["In Review"] = addResult.data;
+	}
+	if (statusOptionsMap["Todo"] && !statusOptionsMap["To Do"]) statusOptionsMap["To Do"] = statusOptionsMap["Todo"];
+	const estimateField = fields.find((f) => f.name === "Estimate");
+	let estimateFieldId = estimateField?.id ?? "";
+	if (!estimateField) {
+		const createFieldResult = await ghExec([
+			"project",
+			"field-create",
+			String(projectNum),
+			"--owner",
+			"@me",
+			"--name",
+			"Estimate",
+			"--data-type",
+			"NUMBER"
+		]);
+		if (!createFieldResult.ok) return fail$2(createFieldResult);
+		const refetch = await getProjectFields(projectNum);
+		if (refetch.ok) {
+			const est = refetch.data.find((f) => f.name === "Estimate");
+			if (est) estimateFieldId = est.id;
+		}
+	}
+	const repoResult = await ghExec([
+		"repo",
+		"view",
+		"--json",
+		"nameWithOwner",
+		"--jq",
+		".nameWithOwner"
+	]);
+	const repo = repoResult.ok ? repoResult.data.trim() : "";
+	const mapping = loadMapping(cwd) ?? createEmptyMapping(repo);
+	mapping.project_number = projectNum;
+	mapping.project_id = projectId;
+	mapping.status_field_id = statusField.id;
+	mapping.status_options = statusOptionsMap;
+	mapping.estimate_field_id = estimateFieldId;
+	if (repo && !mapping.repo) mapping.repo = repo;
+	saveMapping(cwd, mapping);
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Add an issue to a project board.
+*
+* Runs `gh project item-add {num} --owner @me --url {issueUrl} --format json`.
+* Returns the project item ID (different from the issue ID).
+*/
+async function addItemToProject(projectNum, issueUrl) {
+	const result = await ghExec([
+		"project",
+		"item-add",
+		String(projectNum),
+		"--owner",
+		"@me",
+		"--url",
+		issueUrl,
+		"--format",
+		"json"
+	], { parseJson: true });
+	if (!result.ok) return fail$2(result);
+	return {
+		ok: true,
+		data: { item_id: result.data.id }
+	};
+}
+/**
+* Move a project item to a specific status column.
+*
+* Runs `gh project item-edit` with single-select-option-id for the
+* Status field.
+*/
+async function moveItemToStatus(projectId, itemId, statusFieldId, statusOptionId) {
+	const result = await ghExec([
+		"project",
+		"item-edit",
+		"--project-id",
+		projectId,
+		"--id",
+		itemId,
+		"--field-id",
+		statusFieldId,
+		"--single-select-option-id",
+		statusOptionId
+	]);
+	if (!result.ok) return fail$2(result);
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+/**
+* Set the Estimate (story points) field on a project item.
+*
+* Runs `gh project item-edit` with --number flag for the Estimate field.
+*/
+async function setEstimate(projectId, itemId, estimateFieldId, points) {
+	const result = await ghExec([
+		"project",
+		"item-edit",
+		"--project-id",
+		projectId,
+		"--id",
+		itemId,
+		"--field-id",
+		estimateFieldId,
+		"--number",
+		String(points)
+	]);
+	if (!result.ok) return fail$2(result);
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+
+//#endregion
+//#region src/github/milestones.ts
+/**
+* Re-wrap a failed GhResult for a different generic type.
+*/
+function fail$1(result) {
+	return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+}
+/**
+* Create a new GitHub milestone.
+*
+* Uses the REST API: `POST /repos/{owner}/{repo}/milestones`.
+* The `{owner}` and `{repo}` placeholders are auto-resolved by `gh api`.
+*
+* Returns the milestone number and internal ID.
+*/
+async function createMilestone(title, description) {
+	const args = [
+		"api",
+		"repos/{owner}/{repo}/milestones",
+		"-X",
+		"POST",
+		"-f",
+		`title=${title}`,
+		"-f",
+		"state=open"
+	];
+	if (description) args.push("-f", `description=${description}`);
+	const result = await ghExec(args, { parseJson: true });
+	if (!result.ok) return result;
+	return {
+		ok: true,
+		data: {
+			number: result.data.number,
+			id: result.data.id
+		}
+	};
+}
+/**
+* Find an existing milestone by title.
+*
+* Uses the REST API: `GET /repos/{owner}/{repo}/milestones`.
+* Fetches all open milestones and filters by exact title match.
+*
+* Returns null if no milestone with the given title exists.
+*/
+async function findMilestone(title) {
+	const result = await ghExec([
+		"api",
+		"repos/{owner}/{repo}/milestones",
+		"--paginate"
+	], { parseJson: true });
+	if (!result.ok) return fail$1(result);
+	const match = result.data.find((m) => m.title === title);
+	if (!match) return {
+		ok: true,
+		data: null
+	};
+	return {
+		ok: true,
+		data: {
+			number: match.number,
+			id: match.id
+		}
+	};
+}
+/**
+* Ensure a milestone exists, creating it if needed. Idempotent.
+*
+* First attempts to find an existing milestone with the given title.
+* If not found, creates a new one. Returns whether it was newly created.
+*/
+async function ensureMilestone(title, description) {
+	const findResult = await findMilestone(title);
+	if (!findResult.ok) return fail$1(findResult);
+	if (findResult.data) return {
+		ok: true,
+		data: {
+			...findResult.data,
+			created: false
+		}
+	};
+	const createResult = await createMilestone(title, description);
+	if (!createResult.ok) return fail$1(createResult);
+	return {
+		ok: true,
+		data: {
+			...createResult.data,
+			created: true
+		}
+	};
+}
+/**
+* Close a milestone if all its issues are closed.
+*
+* Fetches milestone details via REST API to check `open_issues` count.
+* If open_issues === 0, patches the milestone state to "closed".
+*
+* This implements AC-12: milestones auto-close when all issues are closed.
+*/
+async function closeMilestoneIfComplete(milestoneNumber) {
+	const detailResult = await ghExec(["api", `repos/{owner}/{repo}/milestones/${milestoneNumber}`], { parseJson: true });
+	if (!detailResult.ok) return fail$1(detailResult);
+	const milestone = detailResult.data;
+	if (milestone.state === "closed") return {
+		ok: true,
+		data: { closed: true }
+	};
+	if (milestone.open_issues > 0) return {
+		ok: true,
+		data: { closed: false }
+	};
+	const closeResult = await ghExec([
+		"api",
+		`repos/{owner}/{repo}/milestones/${milestoneNumber}`,
+		"-X",
+		"PATCH",
+		"-f",
+		"state=closed"
+	]);
+	if (!closeResult.ok) return fail$1(closeResult);
+	return {
+		ok: true,
+		data: { closed: true }
+	};
+}
+
+//#endregion
+//#region src/github/sync.ts
+/**
+* Re-wrap a failed GhResult for a different generic type.
+*/
+function fail(result) {
+	return {
+		ok: false,
+		error: result.error,
+		code: result.code
+	};
+}
+/**
+* Batch-fetch issue details via a single GraphQL query.
+*
+* Fetches up to 100 issues per query using node ID lookups.
+* Falls back to sequential `gh issue view` if GraphQL fails.
+*/
+async function batchFetchIssues(repo, issueNumbers) {
+	if (issueNumbers.length === 0) return {
+		ok: true,
+		data: /* @__PURE__ */ new Map()
+	};
+	const [owner, name] = repo.split("/");
+	if (!owner || !name) return {
+		ok: false,
+		error: `Invalid repo format: ${repo}. Expected "owner/repo".`,
+		code: "UNKNOWN"
+	};
+	const BATCH_SIZE = 100;
+	const resultMap = /* @__PURE__ */ new Map();
+	for (let i = 0; i < issueNumbers.length; i += BATCH_SIZE) {
+		const batch = issueNumbers.slice(i, i + BATCH_SIZE);
+		const result = await ghGraphQL(`
+      query {
+        repository(owner: "${owner}", name: "${name}") {
+          ${batch.map((num, idx) => `issue_${idx}: issue(number: ${num}) { number state title labels(first: 20) { nodes { name } } }`).join("\n    ")}
+        }
+      }
+    `);
+		if (!result.ok) return batchFetchIssuesSequential(issueNumbers);
+		const repoData = result.data.repository;
+		for (let idx = 0; idx < batch.length; idx++) {
+			const issueData = repoData[`issue_${idx}`];
+			if (issueData) resultMap.set(issueData.number, {
+				state: issueData.state.toLowerCase(),
+				title: issueData.title,
+				labels: issueData.labels.nodes.map((l) => l.name)
+			});
+		}
+	}
+	return {
+		ok: true,
+		data: resultMap
+	};
+}
+/**
+* Sequential fallback: fetch issues one at a time via `gh issue view`.
+*/
+async function batchFetchIssuesSequential(issueNumbers) {
+	const resultMap = /* @__PURE__ */ new Map();
+	for (const num of issueNumbers) {
+		const result = await ghExec([
+			"issue",
+			"view",
+			String(num),
+			"--json",
+			"state,title,labels"
+		], { parseJson: true });
+		if (result.ok) resultMap.set(num, {
+			state: result.data.state.toLowerCase(),
+			title: result.data.title,
+			labels: result.data.labels.map((l) => l.name)
+		});
+	}
+	return {
+		ok: true,
+		data: resultMap
+	};
+}
+/**
+* Compare local mapping file against GitHub reality.
+*
+* For each tracked issue (phases + todos), fetches current GitHub state
+* and compares against the local mapping. Reports discrepancies in
+* state, title, and labels.
+*
+* Uses batched GraphQL for efficiency (single query for up to 100 issues).
+*/
+async function syncCheck(cwd) {
+	const mapping = loadMapping(cwd);
+	if (!mapping) return {
+		ok: false,
+		error: "github-issues.json does not exist. Run project setup first.",
+		code: "NOT_FOUND"
+	};
+	if (!mapping.repo) return {
+		ok: false,
+		error: "No repo configured in github-issues.json.",
+		code: "NOT_FOUND"
+	};
+	const trackedIssues = [];
+	for (const [phaseNum, phase] of Object.entries(mapping.phases)) {
+		if (phase.tracking_issue.number > 0) trackedIssues.push({
+			issueNumber: phase.tracking_issue.number,
+			localStatus: phase.tracking_issue.status,
+			source: `phase ${phaseNum} tracking`
+		});
+		for (const [taskId, task] of Object.entries(phase.tasks)) if (task.number > 0) trackedIssues.push({
+			issueNumber: task.number,
+			localStatus: task.status,
+			source: `phase ${phaseNum}, task ${taskId}`
+		});
+	}
+	if (mapping.todos) {
+		for (const [todoId, todo] of Object.entries(mapping.todos)) if (todo.number > 0) trackedIssues.push({
+			issueNumber: todo.number,
+			localStatus: todo.status,
+			source: `todo ${todoId}`
+		});
+	}
+	if (trackedIssues.length === 0) return {
+		ok: true,
+		data: {
+			inSync: true,
+			changes: []
+		}
+	};
+	const issueNumbers = trackedIssues.map((t) => t.issueNumber);
+	const fetchResult = await batchFetchIssues(mapping.repo, issueNumbers);
+	if (!fetchResult.ok) return fail(fetchResult);
+	const remoteStates = fetchResult.data;
+	const changes = [];
+	for (const tracked of trackedIssues) {
+		const remote = remoteStates.get(tracked.issueNumber);
+		if (!remote) {
+			changes.push({
+				issueNumber: tracked.issueNumber,
+				field: "existence",
+				localValue: "exists",
+				remoteValue: "not found"
+			});
+			continue;
+		}
+		const isRemoteClosed = remote.state === "closed";
+		const isLocalDone = tracked.localStatus === "Done";
+		if (isRemoteClosed && !isLocalDone) changes.push({
+			issueNumber: tracked.issueNumber,
+			field: "state",
+			localValue: tracked.localStatus,
+			remoteValue: "closed (Done)"
+		});
+		else if (!isRemoteClosed && isLocalDone) changes.push({
+			issueNumber: tracked.issueNumber,
+			field: "state",
+			localValue: "Done",
+			remoteValue: `open (${remote.state})`
+		});
+	}
+	return {
+		ok: true,
+		data: {
+			inSync: changes.length === 0,
+			changes
+		}
+	};
+}
+
 //#endregion
 //#region src/mcp/utils.ts
 /**
@@ -34049,6 +35444,10 @@ function mcpError(error, summary) {
 /**
 * Phase CRUD MCP Tools — Phase operations exposed as MCP tools
 *
+* Integrates with GitHub: phase completion triggers sync check, issue close,
+* board move to Done, and milestone completion check. Find/list enrich
+* responses with GitHub issue data when available.
+*
 * CRITICAL: Never import output() or error() from core — they call process.exit().
 * CRITICAL: Never write to stdout — it is reserved for MCP JSON-RPC protocol.
 * CRITICAL: Never call process.exit() — the server must stay alive after every tool call.
@@ -34061,8 +35460,33 @@ function registerPhaseTools(server) {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
-			const result = findPhaseInternal(cwd, phase);
+			const result = await findPhaseInternal(cwd, phase);
 			if (!result) return mcpError(`Phase ${phase} not found`, "Phase not found");
+			let githubTracking = null;
+			let githubTaskIssues = null;
+			let githubWarning;
+			try {
+				const mapping = loadMapping(cwd);
+				if (mapping && result.phase_number) {
+					const phaseMapping = mapping.phases[result.phase_number];
+					if (phaseMapping) {
+						if (phaseMapping.tracking_issue.number > 0) githubTracking = {
+							number: phaseMapping.tracking_issue.number,
+							status: phaseMapping.tracking_issue.status
+						};
+						const taskEntries = Object.entries(phaseMapping.tasks);
+						if (taskEntries.length > 0) {
+							githubTaskIssues = {};
+							for (const [taskId, task] of taskEntries) if (task.number > 0) githubTaskIssues[taskId] = {
+								number: task.number,
+								status: task.status
+							};
+						}
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub data enrichment failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				found: result.found,
 				directory: result.directory,
@@ -34075,7 +35499,10 @@ function registerPhaseTools(server) {
 				has_research: result.has_research,
 				has_context: result.has_context,
 				has_verification: result.has_verification,
-				archived: result.archived ?? null
+				archived: result.archived ?? null,
+				github_tracking_issue: githubTracking,
+				github_task_issues: githubTaskIssues,
+				...githubWarning ? { github_warning: githubWarning } : {}
 			}, `Found phase ${result.phase_number}: ${result.phase_name ?? "unnamed"}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
@@ -34098,22 +35525,46 @@ function registerPhaseTools(server) {
 				limit,
 				has_more: false
 			}, "No phases directory found");
-			let dirs = listSubDirs(phasesDir);
+			let dirs = await listSubDirs(phasesDir);
 			if (include_archived) {
-				const archived = getArchivedPhaseDirs(cwd);
+				const archived = await getArchivedPhaseDirs(cwd);
 				for (const a of archived) dirs.push(`${a.name} [${a.milestone}]`);
 			}
 			dirs.sort((a, b) => comparePhaseNum(a, b));
 			const total_count = dirs.length;
 			const paginated = dirs.slice(offset, offset + limit);
 			const has_more = offset + limit < total_count;
+			let githubIssueCounts = null;
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const mapping = loadMapping(cwd);
+					if (mapping && Object.keys(mapping.phases).length > 0) {
+						githubIssueCounts = {};
+						for (const [phaseNum, phaseData] of Object.entries(mapping.phases)) {
+							let open = 0;
+							let closed = 0;
+							for (const task of Object.values(phaseData.tasks)) if (task.number > 0) if (task.status === "Done") closed++;
+							else open++;
+							githubIssueCounts[phaseNum] = {
+								open,
+								closed
+							};
+						}
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub enrichment failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				directories: paginated,
 				count: paginated.length,
 				total_count,
 				offset,
 				limit,
-				has_more
+				has_more,
+				github_issue_counts: githubIssueCounts,
+				...githubWarning ? { github_warning: githubWarning } : {}
 			}, `Showing ${paginated.length} of ${total_count} phase(s)`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
@@ -34160,7 +35611,50 @@ function registerPhaseTools(server) {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			let syncDiscrepancies = [];
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const syncResult = await syncCheck(cwd);
+					if (syncResult.ok && !syncResult.data.inSync) syncDiscrepancies = syncResult.data.changes;
+				}
+			} catch (e) {
+				githubWarning = `Sync check failed: ${e.message}`;
+			}
 			const result = await phaseCompleteCore(cwd, phase);
+			let githubClosed = false;
+			let milestoneClosed = false;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const mapping = loadMapping(cwd);
+					if (mapping) {
+						const phaseMapping = mapping.phases[phase];
+						if (phaseMapping) {
+							if (phaseMapping.tracking_issue.number > 0) {
+								if ((await closeIssue(phaseMapping.tracking_issue.number, "completed")).ok) {
+									githubClosed = true;
+									phaseMapping.tracking_issue.status = "Done";
+									if (phaseMapping.tracking_issue.item_id && mapping.status_field_id && mapping.status_options["Done"]) await moveItemToStatus(mapping.project_id, phaseMapping.tracking_issue.item_id, mapping.status_field_id, mapping.status_options["Done"]);
+								}
+							}
+							for (const [_taskId, task] of Object.entries(phaseMapping.tasks)) if (task.number > 0 && task.status !== "Done") {
+								if ((await closeIssue(task.number, "completed")).ok) {
+									task.status = "Done";
+									if (task.item_id && mapping.status_field_id && mapping.status_options["Done"]) await moveItemToStatus(mapping.project_id, task.item_id, mapping.status_field_id, mapping.status_options["Done"]);
+									if (phaseMapping.tracking_issue.number > 0) await updateParentTaskList(phaseMapping.tracking_issue.number, task.number, true);
+								}
+							}
+							saveMapping(cwd, mapping);
+							if (mapping.milestone_id > 0) {
+								const msResult = await closeMilestoneIfComplete(mapping.milestone_id);
+								if (msResult.ok) milestoneClosed = msResult.data.closed;
+							}
+						}
+					}
+				}
+			} catch (e) {
+				githubWarning = (githubWarning ? githubWarning + "; " : "") + `GitHub completion operations failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				completed_phase: result.completed_phase,
 				phase_name: result.phase_name,
@@ -34170,12 +35664,118 @@ function registerPhaseTools(server) {
 				is_last_phase: result.is_last_phase,
 				date: result.date,
 				roadmap_updated: result.roadmap_updated,
-				state_updated: result.state_updated
+				state_updated: result.state_updated,
+				sync_discrepancies: syncDiscrepancies.length > 0 ? syncDiscrepancies : null,
+				github_closed: githubClosed,
+				milestone_closed: milestoneClosed,
+				...githubWarning ? { github_warning: githubWarning } : {}
 			}, `Phase ${phase} marked as complete${result.next_phase ? `, next: Phase ${result.next_phase}` : ""}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}
 	});
+	server.tool("mcp_bounce_issue", "Bounce a task back from In Review to In Progress with a detailed comment explaining what failed. Implements reviewer feedback loop (AC-05).", {
+		issue_number: numberType().describe("GitHub issue number to bounce back"),
+		reason: stringType().describe("Detailed reason why the task is being bounced back (reviewer feedback)")
+	}, async ({ issue_number, reason }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") {
+				const mapping = loadMapping(cwd);
+				if (mapping) {
+					if (updateLocalMappingStatus$1(mapping, issue_number, "In Progress")) {
+						saveMapping(cwd, mapping);
+						return mcpSuccess({
+							mode: "local-only",
+							issue_number,
+							status: "In Progress",
+							local_updated: true,
+							reason
+						}, `Local-only: issue #${issue_number} bounced to In Progress (reason recorded locally)`);
+					}
+				}
+				return mcpSuccess({
+					mode: "local-only",
+					issue_number,
+					reason,
+					note: "Bounce recorded locally. GitHub operations skipped."
+				}, `Local-only: bounce for issue #${issue_number} recorded`);
+			}
+			const mapping = loadMapping(cwd);
+			let githubWarning;
+			let moved = false;
+			let commented = false;
+			try {
+				const commentResult = await postComment(issue_number, `## Bounced Back to In Progress\n\n**Reason:** ${reason}\n\n---\n*Review feedback posted by MAXSIM*`);
+				commented = commentResult.ok;
+				if (!commentResult.ok) githubWarning = `Comment failed: ${commentResult.error}`;
+			} catch (e) {
+				githubWarning = `Comment failed: ${e.message}`;
+			}
+			try {
+				if (mapping) {
+					const issueEntry = findIssueInMapping$2(mapping, issue_number);
+					if (issueEntry?.item_id && mapping.status_field_id && mapping.status_options["In Progress"]) {
+						const moveResult = await moveItemToStatus(mapping.project_id, issueEntry.item_id, mapping.status_field_id, mapping.status_options["In Progress"]);
+						moved = moveResult.ok;
+						if (!moveResult.ok) githubWarning = (githubWarning ? githubWarning + "; " : "") + `Board move failed: ${moveResult.error}`;
+					}
+					updateLocalMappingStatus$1(mapping, issue_number, "In Progress");
+					saveMapping(cwd, mapping);
+				}
+			} catch (e) {
+				githubWarning = (githubWarning ? githubWarning + "; " : "") + `Board move failed: ${e.message}`;
+			}
+			return mcpSuccess({
+				mode: "full",
+				issue_number,
+				status: "In Progress",
+				commented,
+				moved,
+				reason,
+				...githubWarning ? { github_warning: githubWarning } : {}
+			}, `Issue #${issue_number} bounced to In Progress${commented ? " with feedback comment" : ""}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+}
+/**
+* Find an issue entry in the mapping file (searches phases and todos).
+*/
+function findIssueInMapping$2(mapping, issueNumber) {
+	for (const phase of Object.values(mapping.phases)) {
+		if (phase.tracking_issue.number === issueNumber) return phase.tracking_issue;
+		for (const task of Object.values(phase.tasks)) if (task.number === issueNumber) return task;
+	}
+	if (mapping.todos) {
+		for (const todo of Object.values(mapping.todos)) if (todo.number === issueNumber) return todo;
+	}
+	return null;
+}
+/**
+* Update local mapping status for an issue (mutates mapping in-place).
+* Returns true if the issue was found and updated.
+*/
+function updateLocalMappingStatus$1(mapping, issueNumber, status) {
+	for (const phase of Object.values(mapping.phases)) {
+		if (phase.tracking_issue.number === issueNumber) {
+			phase.tracking_issue.status = status;
+			return true;
+		}
+		for (const task of Object.values(phase.tasks)) if (task.number === issueNumber) {
+			task.status = status;
+			return true;
+		}
+	}
+	if (mapping.todos) {
+		for (const todo of Object.values(mapping.todos)) if (todo.number === issueNumber) {
+			todo.status = status;
+			return true;
+		}
+	}
+	return false;
 }
 
 //#endregion
@@ -34203,6 +35803,10 @@ function parseTodoFrontmatter(content) {
 /**
 * Todo CRUD MCP Tools — Todo operations exposed as MCP tools
 *
+* Integrates with GitHub: todo add creates GitHub issue in 'full' mode,
+* todo complete closes GitHub issue and moves to Done on board,
+* todo list enriches with GitHub issue data when available.
+*
 * CRITICAL: Never import output() or error() from core — they call process.exit().
 * CRITICAL: Never write to stdout — it is reserved for MCP JSON-RPC protocol.
 * CRITICAL: Never call process.exit() — the server must stay alive after every tool call.
@@ -34228,12 +35832,55 @@ function registerTodoTools(server) {
 			const filePath = node_path.default.join(pendingDir, filename);
 			const content = `---\ncreated: ${today}\ntitle: ${title}\narea: ${area || "general"}\nphase: ${phase || "unassigned"}\n---\n${description || ""}\n`;
 			node_fs.default.writeFileSync(filePath, content, "utf-8");
+			let githubIssueNumber = null;
+			let githubIssueUrl = null;
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const mapping = loadMapping(cwd);
+					const issueResult = await createTodoIssue({
+						title,
+						description: description || void 0,
+						milestone: mapping?.milestone_title || void 0
+					});
+					if (issueResult.ok) {
+						githubIssueNumber = issueResult.data.number;
+						githubIssueUrl = issueResult.data.url;
+						if (mapping && mapping.project_number > 0) {
+							const issueUrl = `https://github.com/${mapping.repo}/issues/${issueResult.data.number}`;
+							const addResult = await addItemToProject(mapping.project_number, issueUrl);
+							if (addResult.ok) {
+								updateTodoMapping(cwd, filename, {
+									number: issueResult.data.number,
+									node_id: issueResult.data.node_id,
+									item_id: addResult.data.item_id,
+									status: "To Do"
+								});
+								if (mapping.status_field_id && mapping.status_options["To Do"]) await moveItemToStatus(mapping.project_id, addResult.data.item_id, mapping.status_field_id, mapping.status_options["To Do"]);
+							} else {
+								updateTodoMapping(cwd, filename, {
+									number: issueResult.data.number,
+									node_id: issueResult.data.node_id,
+									item_id: "",
+									status: "To Do"
+								});
+								githubWarning = `Issue created but board add failed: ${addResult.error}`;
+							}
+						} else githubWarning = "Issue created but no project board configured for board tracking.";
+					} else githubWarning = `GitHub issue creation failed: ${issueResult.error}`;
+				}
+			} catch (e) {
+				githubWarning = `GitHub operation failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				file: filename,
 				path: `.planning/todos/pending/${filename}`,
 				title,
-				area: area || "general"
-			}, `Todo created: ${title}`);
+				area: area || "general",
+				github_issue_number: githubIssueNumber,
+				github_issue_url: githubIssueUrl,
+				...githubWarning ? { github_warning: githubWarning } : {}
+			}, `Todo created: ${title}${githubIssueNumber ? ` (GitHub #${githubIssueNumber})` : ""}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}
@@ -34252,11 +35899,33 @@ function registerTodoTools(server) {
 			content = `completed: ${today}\n` + content;
 			node_fs.default.writeFileSync(node_path.default.join(completedDir, todo_id), content, "utf-8");
 			node_fs.default.unlinkSync(sourcePath);
+			let githubClosed = false;
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const mapping = loadMapping(cwd);
+					if (mapping?.todos?.[todo_id]) {
+						const todoMapping = mapping.todos[todo_id];
+						if (todoMapping.number > 0) {
+							const closeResult = await closeIssue(todoMapping.number, "completed");
+							githubClosed = closeResult.ok;
+							if (!closeResult.ok) githubWarning = `GitHub issue close failed: ${closeResult.error}`;
+							if (todoMapping.item_id && mapping.status_field_id && mapping.status_options["Done"]) await moveItemToStatus(mapping.project_id, todoMapping.item_id, mapping.status_field_id, mapping.status_options["Done"]);
+							todoMapping.status = "Done";
+							saveMapping(cwd, mapping);
+						}
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub operation failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				completed: true,
 				file: todo_id,
-				date: today
-			}, `Todo completed: ${todo_id}`);
+				date: today,
+				github_closed: githubClosed,
+				...githubWarning ? { github_warning: githubWarning } : {}
+			}, `Todo completed: ${todo_id}${githubClosed ? " (GitHub issue closed)" : ""}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}
@@ -34277,6 +35946,22 @@ function registerTodoTools(server) {
 			if (status === "pending" || status === "all") dirs.push(node_path.default.join(todosBase, "pending"));
 			if (status === "completed" || status === "all") dirs.push(node_path.default.join(todosBase, "completed"));
 			const todos = [];
+			let todoMappings = null;
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const mapping = loadMapping(cwd);
+					if (mapping?.todos) {
+						todoMappings = {};
+						for (const [todoId, data] of Object.entries(mapping.todos)) if (data.number > 0) todoMappings[todoId] = {
+							number: data.number,
+							status: data.status
+						};
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub enrichment failed: ${e.message}`;
+			}
 			for (const dir of dirs) {
 				const dirStatus = dir.endsWith("pending") ? "pending" : "completed";
 				let files = [];
@@ -34288,19 +35973,25 @@ function registerTodoTools(server) {
 				for (const file of files) try {
 					const fm = parseTodoFrontmatter(node_fs.default.readFileSync(node_path.default.join(dir, file), "utf-8"));
 					if (area && fm.area !== area) continue;
-					todos.push({
+					const todoEntry = {
 						file,
 						created: fm.created,
 						title: fm.title,
 						area: fm.area,
 						status: dirStatus,
 						path: `.planning/todos/${dirStatus}/${file}`
-					});
+					};
+					if (todoMappings?.[file]) {
+						todoEntry.github_issue_number = todoMappings[file].number;
+						todoEntry.github_status = todoMappings[file].status;
+					}
+					todos.push(todoEntry);
 				} catch {}
 			}
 			return mcpSuccess({
 				count: todos.length,
-				todos
+				todos,
+				...githubWarning ? { github_warning: githubWarning } : {}
 			}, `${todos.length} todos found`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
@@ -34362,11 +36053,29 @@ function appendToStateSection(content, sectionPattern, entry, placeholderPattern
 /**
 * State Management MCP Tools — STATE.md operations exposed as MCP tools
 *
+* Integrates with GitHub: blocker add/resolve uses best-effort GitHub
+* issue linking when blocker text references issue numbers.
+*
 * CRITICAL: Never import output() or error() from core — they call process.exit().
 * CRITICAL: Never write to stdout — it is reserved for MCP JSON-RPC protocol.
 * CRITICAL: Never call process.exit() — the server must stay alive after every tool call.
 */
 /**
+* Extract GitHub issue numbers from text.
+*
+* Matches patterns like "#42", "issue 42", "issue #42", "blocked by #42".
+* Returns unique issue numbers found.
+*/
+function extractIssueNumbers(text) {
+	const matches = text.matchAll(/#(\d+)|issue\s+#?(\d+)/gi);
+	const numbers = /* @__PURE__ */ new Set();
+	for (const match of matches) {
+		const num = parseInt(match[1] || match[2], 10);
+		if (!Number.isNaN(num) && num > 0) numbers.add(num);
+	}
+	return Array.from(numbers);
+}
+/**
 * Register all state management tools on the MCP server.
 */
 function registerStateTools(server) {
@@ -34448,10 +36157,24 @@ function registerStateTools(server) {
 			const updated = appendToStateSection(node_fs.default.readFileSync(stPath, "utf-8"), /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i, `- ${text}`, [/None\.?\s*\n?/gi, /None yet\.?\s*\n?/gi]);
 			if (!updated) return mcpError("Blockers section not found in STATE.md", "Section not found");
 			node_fs.default.writeFileSync(stPath, updated, "utf-8");
+			let githubLinked = [];
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const issueNumbers = extractIssueNumbers(text);
+					if (issueNumbers.length > 0) {
+						for (const issueNum of issueNumbers) if ((await postComment(issueNum, `**Blocker added in MAXSIM:**\n\n${text}\n\n---\n*Posted by MAXSIM blocker tracking*`)).ok) githubLinked.push(issueNum);
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub linking failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				added: true,
-				blocker: text
-			}, "Blocker added");
+				blocker: text,
+				github_linked_issues: githubLinked.length > 0 ? githubLinked : null,
+				...githubWarning ? { github_warning: githubWarning } : {}
+			}, `Blocker added${githubLinked.length > 0 ? ` (linked to ${githubLinked.map((n) => `#${n}`).join(", ")})` : ""}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}
@@ -34466,17 +36189,37 @@ function registerStateTools(server) {
 			const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
 			const match = content.match(sectionPattern);
 			if (!match) return mcpError("Blockers section not found in STATE.md", "Section not found");
-			let newBody = match[2].split("\n").filter((line) => {
+			const lines = match[2].split("\n");
+			const matchingLines = [];
+			let newBody = lines.filter((line) => {
 				if (!line.startsWith("- ")) return true;
-				return !line.toLowerCase().includes(text.toLowerCase());
+				if (line.toLowerCase().includes(text.toLowerCase())) {
+					matchingLines.push(line);
+					return false;
+				}
+				return true;
 			}).join("\n");
 			if (!newBody.trim() || !newBody.includes("- ")) newBody = "None\n";
 			content = content.replace(sectionPattern, (_match, header) => `${header}${newBody}`);
 			node_fs.default.writeFileSync(stPath, content, "utf-8");
+			let githubCommented = [];
+			let githubWarning;
+			try {
+				if (await detectGitHubMode() === "full") {
+					const issueNumbers = extractIssueNumbers(matchingLines.join(" ") + " " + text);
+					if (issueNumbers.length > 0) {
+						for (const issueNum of issueNumbers) if ((await postComment(issueNum, `**Blocker resolved in MAXSIM:**\n\nResolved blocker matching: "${text}"\n\n---\n*Posted by MAXSIM blocker tracking*`)).ok) githubCommented.push(issueNum);
+					}
+				}
+			} catch (e) {
+				githubWarning = `GitHub comment failed: ${e.message}`;
+			}
 			return mcpSuccess({
 				resolved: true,
-				blocker: text
-			}, "Blocker resolved");
+				blocker: text,
+				github_commented_issues: githubCommented.length > 0 ? githubCommented : null,
+				...githubWarning ? { github_warning: githubWarning } : {}
+			}, `Blocker resolved${githubCommented.length > 0 ? ` (commented on ${githubCommented.map((n) => `#${n}`).join(", ")})` : ""}`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}
@@ -34491,7 +36234,7 @@ function registerStateTools(server) {
 * Ported from maxsim/bin/lib/roadmap.cjs
 */
 async function cmdRoadmapAnalyze(cwd) {
-	const content = await safeReadFileAsync(roadmapPath(cwd));
+	const content = await safeReadFile(roadmapPath(cwd));
 	if (!content) return cmdOk({
 		error: "ROADMAP.md not found",
 		milestones: [],
@@ -34524,7 +36267,7 @@ async function cmdRoadmapAnalyze(cwd) {
 	}
 	let allDirs = [];
 	try {
-		allDirs = await listSubDirsAsync(phasesDir);
+		allDirs = await listSubDirs(phasesDir);
 	} catch {}
 	const phases = await Promise.all(parsedPhases.map(async (p) => {
 		let diskStatus = "no_directory";
@@ -34664,9 +36407,9 @@ function loadRoadmapContext(cwd) {
 	addIfExists(files, cwd, ".planning/ROADMAP.md", "roadmap");
 	return files;
 }
-function loadPhaseContext(cwd, phase) {
+async function loadPhaseContext(cwd, phase) {
 	const files = [];
-	const phaseInfo = findPhaseInternal(cwd, phase);
+	const phaseInfo = await findPhaseInternal(cwd, phase);
 	if (!phaseInfo?.directory) return files;
 	const phaseDir = phaseInfo.directory;
 	try {
@@ -34684,7 +36427,7 @@ function loadPhaseContext(cwd, phase) {
 	}
 	return files;
 }
-function loadArtefakteContext(cwd, phase) {
+async function loadArtefakteContext(cwd, phase) {
 	const files = [];
 	for (const filename of [
 		"DECISIONS.md",
@@ -34692,7 +36435,7 @@ function loadArtefakteContext(cwd, phase) {
 		"NO-GOS.md"
 	]) {
 		if (phase) {
-			const phaseInfo = findPhaseInternal(cwd, phase);
+			const phaseInfo = await findPhaseInternal(cwd, phase);
 			if (phaseInfo?.directory) addIfExists(files, cwd, node_path.default.join(phaseInfo.directory, filename), `artefakt-${filename.toLowerCase()}`);
 		}
 		addIfExists(files, cwd, `.planning/${filename}`, `artefakt-${filename.toLowerCase()}`);
@@ -34709,11 +36452,11 @@ function loadCodebaseContext(cwd, topic) {
 	} catch {}
 	return files;
 }
-function loadHistoryContext(cwd, currentPhase) {
+async function loadHistoryContext(cwd, currentPhase) {
 	const files = [];
 	const pd = phasesPath(cwd);
 	try {
-		const dirs = listSubDirs(pd, true);
+		const dirs = await listSubDirs(pd, true);
 		for (const dir of dirs) {
 			if (currentPhase) {
 				if (dir.match(/^(\d+[A-Z]?(?:\.\d+)?)/i)?.[1] === currentPhase) continue;
@@ -34727,15 +36470,15 @@ function loadHistoryContext(cwd, currentPhase) {
 	}
 	return files;
 }
-function cmdContextLoad(cwd, phase, topic, includeHistory) {
+async function cmdContextLoad(cwd, phase, topic, includeHistory) {
 	const allFiles = [];
 	allFiles.push(...loadProjectContext(cwd));
 	allFiles.push(...loadRoadmapContext(cwd));
-	allFiles.push(...loadArtefakteContext(cwd, phase));
+	allFiles.push(...await loadArtefakteContext(cwd, phase));
 	const selectedDocs = selectCodebaseDocs(topic);
 	allFiles.push(...loadCodebaseContext(cwd, topic));
-	if (phase) allFiles.push(...loadPhaseContext(cwd, phase));
-	if (includeHistory) allFiles.push(...loadHistoryContext(cwd, phase));
+	if (phase) allFiles.push(...await loadPhaseContext(cwd, phase));
+	if (includeHistory) allFiles.push(...await loadHistoryContext(cwd, phase));
 	const seen = /* @__PURE__ */ new Set();
 	const deduped = allFiles.filter((f) => {
 		if (seen.has(f.path)) return false;
@@ -34778,7 +36521,7 @@ function registerContextTools(server) {
 				current_phase = data.current_phase ?? null;
 				next_phase = data.next_phase ?? null;
 			}
-			const stateContent = safeReadFile(planningPath(cwd, "STATE.md"));
+			const stateContent = await safeReadFile(planningPath(cwd, "STATE.md"));
 			if (stateContent) {
 				const statePhase = stateExtractField(stateContent, "Current Phase");
 				if (statePhase) phase_name = statePhase;
@@ -34799,12 +36542,12 @@ function registerContextTools(server) {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
-			const project_vision = safeReadFile(planningPath(cwd, "PROJECT.md"));
-			const config = loadConfig(cwd);
+			const project_vision = await safeReadFile(planningPath(cwd, "PROJECT.md"));
+			const config = await loadConfig(cwd);
 			let phase_context = null;
 			if (phase) {
-				const phaseInfo = findPhaseInternal(cwd, phase);
-				if (phaseInfo) phase_context = safeReadFile(node_path.default.join(phaseInfo.directory, `${phaseInfo.phase_number}-CONTEXT.md`));
+				const phaseInfo = await findPhaseInternal(cwd, phase);
+				if (phaseInfo) phase_context = await safeReadFile(node_path.default.join(phaseInfo.directory, `${phaseInfo.phase_number}-CONTEXT.md`));
 			}
 			return mcpSuccess({
 				project_vision,
@@ -34822,7 +36565,7 @@ function registerContextTools(server) {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
-			const result = cmdContextLoad(cwd, phase, topic, true);
+			const result = await cmdContextLoad(cwd, phase, topic, true);
 			if (!result.ok) return mcpError(result.error, "Context load failed");
 			return mcpSuccess({ context: result.result }, `Context loaded${phase ? ` for phase ${phase}` : ""}${topic ? ` topic "${topic}"` : ""}`);
 		} catch (e) {
@@ -34834,9 +36577,9 @@ function registerContextTools(server) {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
 			return mcpSuccess({
-				project: safeReadFile(planningPath(cwd, "PROJECT.md")),
-				requirements: safeReadFile(planningPath(cwd, "REQUIREMENTS.md")),
-				state: safeReadFile(planningPath(cwd, "STATE.md"))
+				project: await safeReadFile(planningPath(cwd, "PROJECT.md")),
+				requirements: await safeReadFile(planningPath(cwd, "REQUIREMENTS.md")),
+				state: await safeReadFile(planningPath(cwd, "STATE.md"))
 			}, "Project overview loaded");
 		} catch (e) {
 			return mcpError("Failed: " + e.message, "Error occurred");
@@ -34846,7 +36589,7 @@ function registerContextTools(server) {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
-			const phaseInfo = findPhaseInternal(cwd, phase);
+			const phaseInfo = await findPhaseInternal(cwd, phase);
 			if (!phaseInfo) return mcpError(`Phase ${phase} not found`, "Phase not found");
 			const files = [];
 			try {
@@ -34855,7 +36598,7 @@ function registerContextTools(server) {
 					const fullPath = node_path.default.join(phaseInfo.directory, entry);
 					if (node_fs.default.statSync(fullPath).isFile()) files.push({
 						name: entry,
-						content: safeReadFile(fullPath)
+						content: await safeReadFile(fullPath)
 					});
 				}
 			} catch {}
@@ -35006,7 +36749,7 @@ function registerConfigTools(server) {
 					value: result.rawValue ?? result.result
 				}, `Config value for "${key}"`);
 			}
-			return mcpSuccess({ config: loadConfig(cwd) }, "Full configuration loaded");
+			return mcpSuccess({ config: await loadConfig(cwd) }, "Full configuration loaded");
 		} catch (e) {
 			return mcpError("Failed: " + e.message, "Error occurred");
 		}
@@ -35031,6 +36774,897 @@ function registerConfigTools(server) {
 	});
 }
 
+//#endregion
+//#region src/github/types.ts
+const MAXSIM_LABELS = [
+	{
+		name: "maxsim",
+		color: "6f42c1",
+		description: "MAXSIM managed issue"
+	},
+	{
+		name: "phase-task",
+		color: "0075ca",
+		description: "MAXSIM phase task"
+	},
+	{
+		name: "todo",
+		color: "fbca04",
+		description: "MAXSIM todo item"
+	},
+	{
+		name: "imported",
+		color: "e4e669",
+		description: "Imported into MAXSIM tracking"
+	},
+	{
+		name: "superseded",
+		color: "d73a4a",
+		description: "Superseded by newer plan"
+	}
+];
+const FIBONACCI_POINTS = [
+	1,
+	2,
+	3,
+	5,
+	8,
+	13,
+	21,
+	34
+];
+
+//#endregion
+//#region src/github/labels.ts
+/**
+* Ensure all MAXSIM labels exist on the repository.
+*
+* Iterates over MAXSIM_LABELS and runs `gh label create` with `--force`
+* for each label. The `--force` flag updates existing labels with the
+* specified color and description.
+*
+* Continues on individual label failures (logs to stderr).
+* Only fails if ALL labels fail to create.
+*/
+async function ensureLabels() {
+	let successCount = 0;
+	const errors = [];
+	for (const label of MAXSIM_LABELS) {
+		const result = await ghExec([
+			"label",
+			"create",
+			label.name,
+			"--color",
+			label.color,
+			"--description",
+			label.description,
+			"--force"
+		]);
+		if (result.ok) successCount++;
+		else {
+			const errMsg = result.error;
+			console.error(`[maxsim] Failed to create label "${label.name}": ${errMsg}`);
+			errors.push(`${label.name}: ${errMsg}`);
+		}
+	}
+	if (successCount === 0 && errors.length > 0) return {
+		ok: false,
+		error: `All labels failed to create: ${errors.join("; ")}`,
+		code: "UNKNOWN"
+	};
+	return {
+		ok: true,
+		data: void 0
+	};
+}
+
+//#endregion
+//#region src/github/templates.ts
+/**
+* GitHub Issue Templates — Template file generation
+*
+* Installs GitHub Issue Form YAML templates into `.github/ISSUE_TEMPLATE/`
+* for the MAXSIM-managed issue types: phase tasks and todos.
+*
+* These are file-system operations only (no gh CLI needed).
+* Uses synchronous fs to match existing core module patterns.
+*
+* CRITICAL: Never call process.exit().
+*/
+/**
+* Phase task issue template (GitHub Issue Forms YAML format).
+*
+* Used for issues created from MAXSIM phase plans.
+* Labels: maxsim, phase-task
+*/
+const PHASE_TASK_TEMPLATE = `name: "MAXSIM Phase Task"
+description: "Task generated by MAXSIM phase planning"
+labels: ["maxsim", "phase-task"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This issue was auto-generated by MAXSIM.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Task summary
+    validations:
+      required: true
+
+  - type: textarea
+    id: spec
+    attributes:
+      label: Full Specification
+      description: Detailed task specification including actions, criteria, and dependencies
+`;
+/**
+* Todo issue template (GitHub Issue Forms YAML format).
+*
+* Used for issues created from MAXSIM todo items.
+* Labels: maxsim, todo
+*/
+const TODO_TEMPLATE = `name: "MAXSIM Todo"
+description: "Todo item tracked by MAXSIM"
+labels: ["maxsim", "todo"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Brief description of the todo item
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: What defines "done" for this todo?
+`;
+/**
+* Install MAXSIM issue templates into the project's `.github/ISSUE_TEMPLATE/` directory.
+*
+* Creates the directory recursively if it does not exist.
+* Writes two YAML files:
+*   - phase-task.yml (for phase plan tasks)
+*   - todo.yml (for todo items)
+*
+* Overwrites existing templates if present (to ensure latest version).
+* This is a synchronous file write operation (no gh CLI needed).
+*/
+function installIssueTemplates(cwd) {
+	const templateDir = node_path.default.join(cwd, ".github", "ISSUE_TEMPLATE");
+	node_fs.default.mkdirSync(templateDir, { recursive: true });
+	node_fs.default.writeFileSync(node_path.default.join(templateDir, "phase-task.yml"), PHASE_TASK_TEMPLATE, "utf-8");
+	node_fs.default.writeFileSync(node_path.default.join(templateDir, "todo.yml"), TODO_TEMPLATE, "utf-8");
+}
+
+//#endregion
+//#region src/mcp/github-tools.ts
+/**
+* GitHub Issue Lifecycle MCP Tools — GitHub operations exposed as MCP tools
+*
+* Provides MCP tools for issue CRUD, PR creation with auto-close linking (AC-08),
+* sync checking (AC-09), and issue import. Every tool checks detectGitHubMode()
+* and degrades gracefully to local-only behavior when GitHub is not configured.
+*
+* CRITICAL: Never import output() or error() from core — they call process.exit().
+* CRITICAL: Never write to stdout — it is reserved for MCP JSON-RPC protocol.
+* CRITICAL: Never call process.exit() — the server must stay alive after every tool call.
+*/
+/**
+* Register all GitHub issue lifecycle tools on the MCP server.
+*/
+function registerGitHubTools(server) {
+	server.tool("mcp_github_setup", "Set up GitHub integration: create project board, labels, milestone, and issue templates.", { milestone_title: stringType().optional().describe("Milestone title (defaults to current milestone from STATE.md)") }, async ({ milestone_title }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") {
+				installIssueTemplates(cwd);
+				return mcpSuccess({
+					mode: "local-only",
+					templates_installed: true,
+					board_created: false,
+					labels_created: false,
+					milestone_created: false
+				}, "Local-only mode: installed issue templates only. Run `gh auth login` with project scope for full GitHub integration.");
+			}
+			const boardResult = await ensureProjectBoard("MAXSIM Task Board", cwd);
+			if (!boardResult.ok) return mcpError(`Board setup failed: ${boardResult.error}`, "Setup failed");
+			const labelsResult = await ensureLabels();
+			if (!labelsResult.ok) return mcpError(`Label setup failed: ${labelsResult.error}`, "Setup failed");
+			let milestoneData = null;
+			if (milestone_title) {
+				const msResult = await ensureMilestone(milestone_title);
+				if (msResult.ok) {
+					milestoneData = msResult.data;
+					const mapping = loadMapping(cwd);
+					if (mapping) {
+						mapping.milestone_id = msResult.data.number;
+						mapping.milestone_title = milestone_title;
+						saveMapping(cwd, mapping);
+					}
+				}
+			}
+			installIssueTemplates(cwd);
+			return mcpSuccess({
+				mode: "full",
+				board: {
+					number: boardResult.data.number,
+					created: boardResult.data.created
+				},
+				labels_created: true,
+				milestone: milestoneData ? {
+					number: milestoneData.number,
+					title: milestone_title,
+					created: milestoneData.created
+				} : null,
+				templates_installed: true
+			}, `GitHub integration set up: board #${boardResult.data.number}, labels, ${milestoneData ? `milestone "${milestone_title}"` : "no milestone"}, templates`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_create_plan_issues", "Create GitHub issues for all tasks in a finalized plan. Creates task issues and parent tracking issue.", {
+		phase: stringType().describe("Phase number (e.g. \"01\")"),
+		plan: stringType().describe("Plan number (e.g. \"01\")"),
+		phase_name: stringType().describe("Phase description for the tracking issue title"),
+		tasks: arrayType(objectType({
+			taskId: stringType(),
+			title: stringType(),
+			summary: stringType(),
+			actions: arrayType(stringType()),
+			acceptanceCriteria: arrayType(stringType()),
+			dependencies: arrayType(stringType()).optional(),
+			estimate: numberType().optional()
+		})).describe("Array of task objects to create issues for"),
+		milestone: stringType().optional().describe("Milestone title to assign")
+	}, async ({ phase, plan, phase_name, tasks, milestone }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured, issues not created",
+				tasks_count: tasks.length
+			}, "Local-only mode: GitHub issues not created. Run `gh auth login` for full integration.");
+			const mapping = loadMapping(cwd);
+			const result = await createAllPlanIssues({
+				phaseNum: phase,
+				planNum: plan,
+				phaseName: phase_name,
+				tasks,
+				milestone,
+				projectTitle: mapping?.project_number ? void 0 : void 0,
+				cwd
+			});
+			if (!result.ok) return mcpError(`Issue creation failed: ${result.error}`, "Creation failed");
+			if (mapping && mapping.project_number > 0) {
+				const repo = mapping.repo;
+				const allIssueNumbers = [result.data.parentIssue, ...result.data.taskIssues.map((t) => t.issueNumber)];
+				for (const issueNum of allIssueNumbers) {
+					const issueUrl = `https://github.com/${repo}/issues/${issueNum}`;
+					const addResult = await addItemToProject(mapping.project_number, issueUrl);
+					if (addResult.ok) {
+						const taskEntry = result.data.taskIssues.find((t) => t.issueNumber === issueNum);
+						if (taskEntry) updateTaskMapping(cwd, phase, taskEntry.taskId, { item_id: addResult.data.item_id });
+						if (mapping.status_options["To Do"] && mapping.status_field_id) await moveItemToStatus(mapping.project_id, addResult.data.item_id, mapping.status_field_id, mapping.status_options["To Do"]);
+						if (taskEntry && mapping.estimate_field_id) {
+							const taskDef = tasks.find((t) => t.taskId === taskEntry.taskId);
+							if (taskDef?.estimate) await setEstimate(mapping.project_id, addResult.data.item_id, mapping.estimate_field_id, taskDef.estimate);
+						}
+					}
+				}
+			}
+			return mcpSuccess({
+				mode: "full",
+				parent_issue: result.data.parentIssue,
+				task_issues: result.data.taskIssues,
+				total_created: result.data.taskIssues.length + 1
+			}, `Created ${result.data.taskIssues.length} task issues + parent tracking issue #${result.data.parentIssue}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_create_todo_issue", "Create a GitHub issue for a todo item.", {
+		title: stringType().describe("Todo title"),
+		description: stringType().optional().describe("Todo description"),
+		acceptance_criteria: arrayType(stringType()).optional().describe("Acceptance criteria list")
+	}, async ({ title, description, acceptance_criteria }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Use mcp_add_todo for local todo tracking.",
+				title
+			}, "Local-only mode: GitHub todo issue not created.");
+			const mapping = loadMapping(cwd);
+			const result = await createTodoIssue({
+				title,
+				description,
+				acceptanceCriteria: acceptance_criteria,
+				milestone: mapping?.milestone_title || void 0
+			});
+			if (!result.ok) return mcpError(`Todo issue creation failed: ${result.error}`, "Creation failed");
+			if (mapping && mapping.project_number > 0) {
+				const issueUrl = `https://github.com/${mapping.repo}/issues/${result.data.number}`;
+				const addResult = await addItemToProject(mapping.project_number, issueUrl);
+				if (addResult.ok && mapping) {
+					if (!mapping.todos) mapping.todos = {};
+					mapping.todos[`todo-${result.data.number}`] = {
+						number: result.data.number,
+						node_id: result.data.node_id,
+						item_id: addResult.data.item_id,
+						status: "To Do"
+					};
+					saveMapping(cwd, mapping);
+				}
+			}
+			return mcpSuccess({
+				mode: "full",
+				issue_number: result.data.number,
+				url: result.data.url
+			}, `Created todo issue #${result.data.number}: ${title}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_move_issue", "Move a GitHub issue to a new status column (To Do, In Progress, In Review, Done).", {
+		issue_number: numberType().describe("GitHub issue number"),
+		status: enumType([
+			"To Do",
+			"In Progress",
+			"In Review",
+			"Done"
+		]).describe("Target status column")
+	}, async ({ issue_number, status }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			const mode = await detectGitHubMode();
+			const mapping = loadMapping(cwd);
+			if (mode === "local-only") {
+				if (mapping) {
+					if (updateLocalMappingStatus(mapping, issue_number, status)) {
+						saveMapping(cwd, mapping);
+						return mcpSuccess({
+							mode: "local-only",
+							issue_number,
+							status,
+							local_updated: true
+						}, `Local mapping updated: issue #${issue_number} -> ${status}`);
+					}
+				}
+				return mcpError(`Issue #${issue_number} not found in local mapping`, "Issue not tracked");
+			}
+			if (!mapping) return mcpError("github-issues.json not found. Run mcp_github_setup first.", "Setup required");
+			const issueEntry = findIssueInMapping$1(mapping, issue_number);
+			if (!issueEntry) return mcpError(`Issue #${issue_number} not found in local mapping`, "Issue not tracked");
+			if (!issueEntry.item_id) return mcpError(`Issue #${issue_number} has no project item_id. It may not have been added to the board.`, "Not on board");
+			const statusOptionId = mapping.status_options[status];
+			if (!statusOptionId) return mcpError(`Status "${status}" not found in project board options`, "Invalid status");
+			const moveResult = await moveItemToStatus(mapping.project_id, issueEntry.item_id, mapping.status_field_id, statusOptionId);
+			if (!moveResult.ok) return mcpError(`Move failed: ${moveResult.error}`, "Move failed");
+			updateLocalMappingStatus(mapping, issue_number, status);
+			saveMapping(cwd, mapping);
+			return mcpSuccess({
+				mode: "full",
+				issue_number,
+				status,
+				moved: true
+			}, `Issue #${issue_number} moved to "${status}"`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_close_issue", "Close a GitHub issue as completed or not planned.", {
+		issue_number: numberType().describe("GitHub issue number"),
+		reason: enumType(["completed", "not_planned"]).optional().default("completed").describe("Close reason")
+	}, async ({ issue_number, reason }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot close remote issue.",
+				issue_number
+			}, "Local-only mode: cannot close GitHub issue.");
+			const result = await closeIssue(issue_number, reason);
+			if (!result.ok) return mcpError(`Close failed: ${result.error}`, "Close failed");
+			const mapping = loadMapping(cwd);
+			if (mapping) {
+				const issueEntry = findIssueInMapping$1(mapping, issue_number);
+				if (issueEntry?.item_id && mapping.status_options["Done"] && mapping.status_field_id) await moveItemToStatus(mapping.project_id, issueEntry.item_id, mapping.status_field_id, mapping.status_options["Done"]);
+				updateLocalMappingStatus(mapping, issue_number, "Done");
+				saveMapping(cwd, mapping);
+			}
+			return mcpSuccess({
+				mode: "full",
+				issue_number,
+				reason,
+				closed: true
+			}, `Issue #${issue_number} closed (${reason})`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_post_comment", "Post a progress comment on a GitHub issue.", {
+		issue_number: numberType().describe("GitHub issue number"),
+		body: stringType().describe("Comment body (markdown supported)")
+	}, async ({ issue_number, body }) => {
+		try {
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot post comment.",
+				issue_number
+			}, "Local-only mode: cannot post comment on GitHub issue.");
+			const result = await postComment(issue_number, body);
+			if (!result.ok) return mcpError(`Comment failed: ${result.error}`, "Comment failed");
+			return mcpSuccess({
+				mode: "full",
+				issue_number,
+				commented: true
+			}, `Comment posted on issue #${issue_number}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_import_issue", "Import an external GitHub issue into MAXSIM tracking.", { issue_number: numberType().describe("GitHub issue number to import") }, async ({ issue_number }) => {
+		try {
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot import issue.",
+				issue_number
+			}, "Local-only mode: cannot import GitHub issue.");
+			const result = await importExternalIssue(issue_number);
+			if (!result.ok) return mcpError(`Import failed: ${result.error}`, "Import failed");
+			return mcpSuccess({
+				mode: "full",
+				issue_number: result.data.number,
+				title: result.data.title,
+				labels: result.data.labels,
+				imported: true
+			}, `Imported issue #${result.data.number}: "${result.data.title}". Assign to a phase or todo for tracking.`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_sync_check", "Check for external changes to tracked GitHub issues.", {}, async () => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Sync check not available.",
+				in_sync: true,
+				changes: []
+			}, "Local-only mode: sync check skipped.");
+			const result = await syncCheck(cwd);
+			if (!result.ok) return mcpError(`Sync check failed: ${result.error}`, "Sync failed");
+			return mcpSuccess({
+				mode: "full",
+				in_sync: result.data.inSync,
+				changes: result.data.changes,
+				change_count: result.data.changes.length
+			}, result.data.inSync ? "All tracked issues are in sync with GitHub." : `${result.data.changes.length} discrepancies found between local mapping and GitHub.`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_supersede_plan", "Close old plan issues and link to new plan issues.", {
+		phase: stringType().describe("Phase number"),
+		old_plan: stringType().describe("Old plan number to supersede"),
+		new_plan: stringType().describe("New plan number that replaces it")
+	}, async ({ phase, old_plan, new_plan }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot supersede plan issues.",
+				phase,
+				old_plan,
+				new_plan
+			}, "Local-only mode: plan supersession skipped.");
+			const mapping = loadMapping(cwd);
+			if (!mapping) return mcpError("github-issues.json not found. Run mcp_github_setup first.", "Setup required");
+			const newPhaseMapping = mapping.phases[phase];
+			if (!newPhaseMapping) return mcpError(`Phase ${phase} not found in mapping. Create new plan issues first.`, "Phase not found");
+			const result = await supersedePlanIssues({
+				phaseNum: phase,
+				oldPlanNum: old_plan,
+				newPlanNum: new_plan,
+				newIssueNumbers: Object.entries(newPhaseMapping.tasks).map(([taskId, task]) => ({
+					taskId,
+					issueNumber: task.number
+				})),
+				cwd
+			});
+			if (!result.ok) return mcpError(`Supersession failed: ${result.error}`, "Supersession failed");
+			return mcpSuccess({
+				mode: "full",
+				phase,
+				old_plan,
+				new_plan,
+				superseded: true
+			}, `Plan ${phase}-${old_plan} superseded by ${phase}-${new_plan}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_create_pr", "Create a pull request with auto-close linking for tracked GitHub issues. Generates PR description with Closes #N lines (AC-08).", {
+		issue_numbers: arrayType(numberType()).describe("Issue numbers to auto-close when PR merges"),
+		branch: stringType().describe("Source branch name for the PR"),
+		title: stringType().describe("PR title"),
+		base: stringType().optional().default("main").describe("Base branch (default: main)"),
+		additional_context: stringType().optional().describe("Additional context to include in PR body"),
+		draft: booleanType().optional().default(false).describe("Create as draft PR")
+	}, async ({ issue_numbers, branch, title, base, additional_context, draft }) => {
+		try {
+			const mode = await detectGitHubMode();
+			const prBody = buildPrBody(issue_numbers, additional_context);
+			if (mode === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. PR not created. Use the body below to create manually.",
+				pr_body: prBody,
+				issues_linked: issue_numbers
+			}, "Local-only mode: PR body generated but PR not created.");
+			const args = [
+				"pr",
+				"create",
+				"--title",
+				title,
+				"--body",
+				prBody,
+				"--head",
+				branch
+			];
+			if (base) args.push("--base", base);
+			if (draft) args.push("--draft");
+			const createResult = await ghExec(args);
+			if (!createResult.ok) return mcpError(`PR creation failed: ${createResult.error}`, "PR creation failed");
+			const prUrl = createResult.data.trim();
+			const prNumberMatch = prUrl.match(/\/pull\/(\d+)/);
+			return mcpSuccess({
+				mode: "full",
+				pr_number: prNumberMatch ? parseInt(prNumberMatch[1], 10) : null,
+				pr_url: prUrl,
+				issues_linked: issue_numbers,
+				draft
+			}, `PR${draft ? " (draft)" : ""} created: ${prUrl} — auto-closes ${issue_numbers.map((n) => `#${n}`).join(", ")}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+}
+/**
+* Find an issue entry in the mapping file (searches phases and todos).
+*/
+function findIssueInMapping$1(mapping, issueNumber) {
+	for (const phase of Object.values(mapping.phases)) {
+		if (phase.tracking_issue.number === issueNumber) return phase.tracking_issue;
+		for (const task of Object.values(phase.tasks)) if (task.number === issueNumber) return task;
+	}
+	if (mapping.todos) {
+		for (const todo of Object.values(mapping.todos)) if (todo.number === issueNumber) return todo;
+	}
+	return null;
+}
+/**
+* Update local mapping status for an issue (mutates mapping in-place).
+* Returns true if the issue was found and updated.
+*/
+function updateLocalMappingStatus(mapping, issueNumber, status) {
+	for (const phase of Object.values(mapping.phases)) {
+		if (phase.tracking_issue.number === issueNumber) {
+			phase.tracking_issue.status = status;
+			return true;
+		}
+		for (const task of Object.values(phase.tasks)) if (task.number === issueNumber) {
+			task.status = status;
+			return true;
+		}
+	}
+	if (mapping.todos) {
+		for (const todo of Object.values(mapping.todos)) if (todo.number === issueNumber) {
+			todo.status = status;
+			return true;
+		}
+	}
+	return false;
+}
+
+//#endregion
+//#region src/mcp/board-tools.ts
+/**
+* Board Query MCP Tools — Project board operations exposed as MCP tools
+*
+* Provides MCP tools for querying the GitHub project board, searching issues,
+* getting issue details, and setting estimates. Every tool checks detectGitHubMode()
+* and degrades gracefully to local-only behavior when GitHub is not configured.
+*
+* CRITICAL: Never import output() or error() from core — they call process.exit().
+* CRITICAL: Never write to stdout — it is reserved for MCP JSON-RPC protocol.
+* CRITICAL: Never call process.exit() — the server must stay alive after every tool call.
+*/
+/**
+* Register all board query tools on the MCP server.
+*/
+function registerBoardTools(server) {
+	server.tool("mcp_query_board", "Query the GitHub project board. Returns all items with their status, estimates, and issue details.", {
+		status: enumType([
+			"To Do",
+			"In Progress",
+			"In Review",
+			"Done"
+		]).optional().describe("Filter by status column"),
+		phase: stringType().optional().describe("Filter by phase number (matches issue title prefix)")
+	}, async ({ status, phase }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			const mode = await detectGitHubMode();
+			const mapping = loadMapping(cwd);
+			if (mode === "local-only") {
+				if (!mapping) return mcpSuccess({
+					mode: "local-only",
+					items: [],
+					count: 0
+				}, "Local-only mode: no mapping file found.");
+				const items = buildLocalBoardItems(mapping, status, phase);
+				return mcpSuccess({
+					mode: "local-only",
+					items,
+					count: items.length
+				}, `Local-only mode: ${items.length} items from local mapping.`);
+			}
+			if (!mapping || !mapping.project_number) return mcpError("No project board configured. Run mcp_github_setup first.", "Setup required");
+			const result = await ghExec([
+				"project",
+				"item-list",
+				String(mapping.project_number),
+				"--owner",
+				"@me",
+				"--format",
+				"json"
+			], { parseJson: true });
+			if (!result.ok) return mcpError(`Board query failed: ${result.error}`, "Query failed");
+			let items = result.data.items || [];
+			if (status) items = items.filter((item) => item.status === status);
+			if (phase) {
+				const phasePrefix = `[P${phase}]`;
+				const phasePrefixAlt = `[Phase ${phase}]`;
+				items = items.filter((item) => item.title?.includes(phasePrefix) || item.title?.includes(phasePrefixAlt) || item.content?.title?.includes(phasePrefix) || item.content?.title?.includes(phasePrefixAlt));
+			}
+			const formatted = items.map((item) => ({
+				item_id: item.id,
+				title: item.content?.title ?? item.title,
+				issue_number: item.content?.number ?? null,
+				status: item.status ?? "No Status",
+				url: item.content?.url ?? null
+			}));
+			return mcpSuccess({
+				mode: "full",
+				items: formatted,
+				count: formatted.length
+			}, `Board query: ${formatted.length} items${status ? ` in "${status}"` : ""}${phase ? ` for phase ${phase}` : ""}`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_search_issues", "Search GitHub issues by label, milestone, state, or text query.", {
+		labels: arrayType(stringType()).optional().describe("Filter by label names"),
+		milestone: stringType().optional().describe("Filter by milestone title"),
+		state: enumType([
+			"open",
+			"closed",
+			"all"
+		]).optional().default("open").describe("Filter by issue state"),
+		query: stringType().optional().describe("Text search query")
+	}, async ({ labels, milestone, state, query }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (await detectGitHubMode() === "local-only") {
+				const mapping = loadMapping(cwd);
+				if (!mapping) return mcpSuccess({
+					mode: "local-only",
+					issues: [],
+					count: 0
+				}, "Local-only mode: no mapping file found.");
+				const items = buildLocalSearchResults(mapping, state);
+				return mcpSuccess({
+					mode: "local-only",
+					issues: items,
+					count: items.length
+				}, `Local-only mode: ${items.length} items from local mapping.`);
+			}
+			const args = [
+				"issue",
+				"list",
+				"--json",
+				"number,title,state,labels,milestone",
+				"--limit",
+				"100"
+			];
+			if (state && state !== "all") args.push("--state", state);
+			else if (state === "all") args.push("--state", "all");
+			if (labels && labels.length > 0) for (const label of labels) args.push("--label", label);
+			if (milestone) args.push("--milestone", milestone);
+			if (query) args.push("--search", query);
+			const result = await ghExec(args, { parseJson: true });
+			if (!result.ok) return mcpError(`Search failed: ${result.error}`, "Search failed");
+			const issues = result.data.map((issue) => ({
+				number: issue.number,
+				title: issue.title,
+				state: issue.state,
+				labels: issue.labels.map((l) => l.name),
+				milestone: issue.milestone?.title ?? null
+			}));
+			return mcpSuccess({
+				mode: "full",
+				issues,
+				count: issues.length
+			}, `Found ${issues.length} issues`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_get_issue_detail", "Get full details of a specific GitHub issue including comments.", { issue_number: numberType().describe("GitHub issue number") }, async ({ issue_number }) => {
+		try {
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot fetch issue details.",
+				issue_number
+			}, "Local-only mode: cannot fetch issue details.");
+			const result = await ghExec([
+				"issue",
+				"view",
+				String(issue_number),
+				"--json",
+				"number,title,body,state,labels,comments,assignees"
+			], { parseJson: true });
+			if (!result.ok) return mcpError(`Fetch failed: ${result.error}`, "Fetch failed");
+			const issue = result.data;
+			return mcpSuccess({
+				mode: "full",
+				number: issue.number,
+				title: issue.title,
+				body: issue.body,
+				state: issue.state,
+				labels: issue.labels.map((l) => l.name),
+				assignees: issue.assignees.map((a) => a.login),
+				comments: issue.comments.map((c) => ({
+					author: c.author.login,
+					body: c.body,
+					created_at: c.createdAt
+				})),
+				comment_count: issue.comments.length
+			}, `Issue #${issue.number}: ${issue.title} (${issue.state})`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+	server.tool("mcp_set_estimate", "Set Fibonacci story points on a GitHub issue.", {
+		issue_number: numberType().describe("GitHub issue number"),
+		points: numberType().describe("Fibonacci story points (1, 2, 3, 5, 8, 13, 21, 34)")
+	}, async ({ issue_number, points }) => {
+		try {
+			const cwd = detectProjectRoot();
+			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
+			if (!FIBONACCI_POINTS.includes(points)) return mcpError(`Invalid points: ${points}. Must be one of: ${FIBONACCI_POINTS.join(", ")}`, "Validation failed");
+			if (await detectGitHubMode() === "local-only") return mcpSuccess({
+				mode: "local-only",
+				warning: "GitHub not configured. Cannot set estimate.",
+				issue_number,
+				points
+			}, "Local-only mode: cannot set estimate on GitHub project.");
+			const mapping = loadMapping(cwd);
+			if (!mapping) return mcpError("github-issues.json not found. Run mcp_github_setup first.", "Setup required");
+			if (!mapping.estimate_field_id) return mcpError("Estimate field not configured. Re-run mcp_github_setup.", "Setup required");
+			const issueEntry = findIssueInMapping(mapping, issue_number);
+			if (!issueEntry) return mcpError(`Issue #${issue_number} not found in local mapping`, "Issue not tracked");
+			if (!issueEntry.item_id) return mcpError(`Issue #${issue_number} has no project item_id. It may not have been added to the board.`, "Not on board");
+			const result = await setEstimate(mapping.project_id, issueEntry.item_id, mapping.estimate_field_id, points);
+			if (!result.ok) return mcpError(`Set estimate failed: ${result.error}`, "Estimate failed");
+			return mcpSuccess({
+				mode: "full",
+				issue_number,
+				points,
+				set: true
+			}, `Estimate set: issue #${issue_number} = ${points} points`);
+		} catch (e) {
+			return mcpError(e.message, "Operation failed");
+		}
+	});
+}
+/**
+* Find an issue entry in the mapping file (searches phases and todos).
+*/
+function findIssueInMapping(mapping, issueNumber) {
+	for (const phase of Object.values(mapping.phases)) {
+		if (phase.tracking_issue.number === issueNumber) return phase.tracking_issue;
+		for (const task of Object.values(phase.tasks)) if (task.number === issueNumber) return task;
+	}
+	if (mapping.todos) {
+		for (const todo of Object.values(mapping.todos)) if (todo.number === issueNumber) return todo;
+	}
+	return null;
+}
+/**
+* Build local board items from the mapping file (for local-only mode).
+*/
+function buildLocalBoardItems(mapping, statusFilter, phaseFilter) {
+	const items = [];
+	for (const [phaseNum, phase] of Object.entries(mapping.phases)) {
+		if (phaseFilter && phaseNum !== phaseFilter) continue;
+		if (phase.tracking_issue.number > 0) {
+			const entry = {
+				issue_number: phase.tracking_issue.number,
+				title: `[Phase ${phaseNum}] Tracking`,
+				status: phase.tracking_issue.status,
+				source: `phase ${phaseNum}`
+			};
+			if (!statusFilter || entry.status === statusFilter) items.push(entry);
+		}
+		for (const [taskId, task] of Object.entries(phase.tasks)) if (task.number > 0) {
+			const entry = {
+				issue_number: task.number,
+				title: `[P${phaseNum}] Task ${taskId}`,
+				status: task.status,
+				source: `phase ${phaseNum}, task ${taskId}`
+			};
+			if (!statusFilter || entry.status === statusFilter) items.push(entry);
+		}
+	}
+	if (!phaseFilter && mapping.todos) {
+		for (const [todoId, todo] of Object.entries(mapping.todos)) if (todo.number > 0) {
+			const entry = {
+				issue_number: todo.number,
+				title: `Todo: ${todoId}`,
+				status: todo.status,
+				source: `todo ${todoId}`
+			};
+			if (!statusFilter || entry.status === statusFilter) items.push(entry);
+		}
+	}
+	return items;
+}
+/**
+* Build local search results from the mapping file (for local-only mode).
+*/
+function buildLocalSearchResults(mapping, stateFilter) {
+	const items = [];
+	for (const [phaseNum, phase] of Object.entries(mapping.phases)) for (const [taskId, task] of Object.entries(phase.tasks)) if (task.number > 0) {
+		const state = task.status === "Done" ? "closed" : "open";
+		if (stateFilter && stateFilter !== "all" && state !== stateFilter) continue;
+		items.push({
+			issue_number: task.number,
+			title: `[P${phaseNum}] Task ${taskId}`,
+			state,
+			source: `phase ${phaseNum}`
+		});
+	}
+	if (mapping.todos) {
+		for (const [todoId, todo] of Object.entries(mapping.todos)) if (todo.number > 0) {
+			const state = todo.status === "Done" ? "closed" : "open";
+			if (stateFilter && stateFilter !== "all" && state !== stateFilter) continue;
+			items.push({
+				issue_number: todo.number,
+				title: `Todo: ${todoId}`,
+				state,
+				source: "todo"
+			});
+		}
+	}
+	return items;
+}
+
 //#endregion
 //#region src/mcp/index.ts
 /**
@@ -35043,6 +37677,8 @@ function registerAllTools(server) {
 	registerContextTools(server);
 	registerRoadmapTools(server);
 	registerConfigTools(server);
+	registerGitHubTools(server);
+	registerBoardTools(server);
 }
 
 //#endregion