substrate-ai 0.2.4 → 0.2.6

package/dist/{run-D3ZscMlL.js → run-0IlA2ubQ.js}

@@ -13,6 +13,7 @@ import { dirname as dirname$1, join as join$1, resolve as resolve$1 } from "node
 import BetterSqlite3 from "better-sqlite3";
 import { fileURLToPath } from "node:url";
 import { existsSync as existsSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1 } from "node:fs";
+import { freemem } from "node:os";
 import { randomUUID } from "node:crypto";
 import { readFile as readFile$1, stat as stat$1 } from "node:fs/promises";
 
@@ -1024,6 +1025,21 @@ function validateStopAfterFromConflict(stopAfter, from) {
 
 //#endregion
 //#region src/cli/commands/pipeline-shared.ts
+/**
+* Parse a DB timestamp string to a Date, correctly treating it as UTC.
+*
+* SQLite stores timestamps as "YYYY-MM-DD HH:MM:SS" without a timezone suffix.
+* JavaScript's Date constructor parses strings without a timezone suffix as
+* *local time*, which causes staleness/duration to be calculated incorrectly
+* on machines not in UTC.
+*
+* Fix: append 'Z' if the string has no timezone marker so it is always
+* parsed as UTC.
+*/
+function parseDbTimestampAsUtc(ts) {
+	if (ts.endsWith("Z") || /[+-]\d{2}:\d{2}$/.test(ts)) return new Date(ts);
+	return new Date(ts.replace(" ", "T") + "Z");
+}
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
@@ -1197,7 +1213,7 @@ function buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCou
 		decisions_count: decisionsCount,
 		stories_count: storiesCount,
 		last_activity: run.updated_at,
-		staleness_seconds: Math.round((Date.now() - new Date(run.updated_at).getTime()) / 1e3)
+		staleness_seconds: Math.round((Date.now() - parseDbTimestampAsUtc(run.updated_at).getTime()) / 1e3)
 	};
 }
 /**
@@ -1817,6 +1833,53 @@ const PIPELINE_EVENT_METADATA = [
 			}
 		]
 	},
+	{
+		type: "supervisor:poll",
+		description: "Heartbeat each poll (JSON only).",
+		when: "Per cycle.",
+		fields: [
+			{
+				name: "ts",
+				type: "string",
+				description: "Timestamp."
+			},
+			{
+				name: "run_id",
+				type: "string|null",
+				description: "Run ID."
+			},
+			{
+				name: "verdict",
+				type: "HEALTHY|STALLED|NO_PIPELINE_RUNNING",
+				description: "Verdict."
+			},
+			{
+				name: "staleness_seconds",
+				type: "number",
+				description: "Seconds stale."
+			},
+			{
+				name: "stories",
+				type: "object",
+				description: "active/completed/escalated."
+			},
+			{
+				name: "story_details",
+				type: "object",
+				description: "phase+cycles per story."
+			},
+			{
+				name: "tokens",
+				type: "object",
+				description: "input/output/cost_usd."
+			},
+			{
+				name: "process",
+				type: "object",
+				description: "pid/child/zombie counts."
+			}
+		]
+	},
 	{
 		type: "supervisor:kill",
 		description: "Supervisor killed stalled pipeline process tree.",
@@ -2238,42 +2301,34 @@ function generateInteractionPatternsSection() {
 Use this decision flowchart when handling events from \`substrate run --events\`:
 
 ### On \`story:done\` with \`result: success\`
-- Report successful completion to the user.
-- Note the story key and number of review_cycles for telemetry.
+- Report success to the user.
 
 ### On \`story:done\` with \`result: failed\`
-- Report failure to the user with the story key.
-- Suggest checking logs or running \`substrate status\` for details.
+- Report failure with the story key.
 
 ### On \`story:escalation\`
-- Read the \`issues\` array. Each issue has \`severity\`, \`file\` (path:line), and \`desc\`.
-- Present the issues to the user grouped by severity.
-- Offer to fix the issues or explain them.
-- Ask the user whether to retry or abandon the story.
+- Read \`issues\`: each has \`severity\`, \`file\`, \`desc\`.
+- Present grouped by severity; ask user to retry or abandon.
 
 ### On \`story:phase\` with \`verdict: NEEDS_MINOR_FIXES\`
-- The story passed code review but has minor suggestions.
-- Offer to apply the fixes or skip.
-- This is non-blocking — pipeline continues unless you intervene.
+- Non-blocking minor suggestions. Offer to apply or skip.
 
 ### On \`story:warn\`
-- Inform the user of the warning message but do NOT treat it as an error.
-- Common warnings: token ceiling truncation, partial batch failures.
-- Pipeline continues normally after a warn event.
+- Non-blocking warning; pipeline continues normally.
 
 ### On \`story:log\`
-- These are informational only.
-- Display if verbose mode is active; otherwise buffer or discard.
+- Informational only. Display in verbose mode.
 
 ### On \`pipeline:complete\`
-- Summarize results: report \`succeeded.length\` successes.
-- List any \`failed\` or \`escalated\` stories with reasons if available.
-- This is always the last event emitted.
+- Summarize \`succeeded\`, \`failed\`, \`escalated\` counts.
 
 ## Supervisor Interaction Patterns
 
 Patterns for \`substrate supervisor --output-format json\` events:
 
+### On \`supervisor:poll\`
+- Track \`verdict\` and \`tokens.cost_usd\` each cycle. JSON only.
+
 ### On \`supervisor:summary\`
 - Summarize \`succeeded\`, \`failed\`, \`escalated\` counts and \`restarts\`.
 - Offer analysis: \`substrate metrics --analysis <run_id> --output-format json\`.
@@ -2786,6 +2841,8 @@ const logger$12 = createLogger("agent-dispatch");
 const SHUTDOWN_GRACE_MS = 1e4;
 const SHUTDOWN_MAX_WAIT_MS = 3e4;
 const CHARS_PER_TOKEN = 4;
+const MIN_FREE_MEMORY_BYTES = 512 * 1024 * 1024;
+const MEMORY_PRESSURE_POLL_MS = 1e4;
 var MutableDispatchHandle = class {
 	id;
 	status;
@@ -2806,6 +2863,7 @@ var DispatcherImpl = class {
 	_running = new Map();
 	_queue = [];
 	_shuttingDown = false;
+	_memoryPressureTimer = null;
 	constructor(eventBus, adapterRegistry, config) {
 		this._eventBus = eventBus;
 		this._adapterRegistry = adapterRegistry;
@@ -2820,7 +2878,7 @@ var DispatcherImpl = class {
 		const id = randomUUID();
 		const resultPromise = new Promise((resolve$2, reject) => {
 			const typedResolve = resolve$2;
-			if (this._running.size < this._config.maxConcurrency) {
+			if (this._running.size < this._config.maxConcurrency && !this._isMemoryPressured()) {
 				this._reserveSlot(id);
 				this._startDispatch(id, request, typedResolve).catch((err) => {
 					this._running.delete(id);
@@ -2881,6 +2939,7 @@ var DispatcherImpl = class {
 	}
 	async shutdown() {
 		this._shuttingDown = true;
+		this._stopMemoryPressureTimer();
 		logger$12.info({
 			running: this._running.size,
 			queued: this._queue.length
@@ -2951,6 +3010,8 @@ var DispatcherImpl = class {
 		});
 		const timeoutMs = timeout ?? this._config.defaultTimeouts[taskType] ?? DEFAULT_TIMEOUTS[taskType] ?? 3e5;
 		const env = { ...process.env };
+		const parentNodeOpts = env["NODE_OPTIONS"] ?? "";
+		if (!parentNodeOpts.includes("--max-old-space-size")) env["NODE_OPTIONS"] = `${parentNodeOpts} --max-old-space-size=512`.trim();
 		if (cmd.env !== void 0) Object.assign(env, cmd.env);
 		if (cmd.unsetEnvKeys !== void 0) for (const key of cmd.unsetEnvKeys) delete env[key];
 		const proc = spawn(cmd.binary, cmd.args, {
@@ -3157,9 +3218,16 @@ var DispatcherImpl = class {
 		this._running.set(id, placeholder);
 	}
 	_drainQueue() {
-		if (this._queue.length === 0) return;
+		if (this._queue.length === 0) {
+			this._stopMemoryPressureTimer();
+			return;
+		}
 		if (this._running.size >= this._config.maxConcurrency) return;
 		if (this._shuttingDown) return;
+		if (this._isMemoryPressured()) {
+			this._startMemoryPressureTimer();
+			return;
+		}
 		const next = this._queue.shift();
 		if (next === void 0) return;
 		next.handle.status = "running";
@@ -3173,6 +3241,30 @@ var DispatcherImpl = class {
 		const idx = this._queue.findIndex((q) => q.id === id);
 		if (idx !== -1) this._queue.splice(idx, 1);
 	}
+	_isMemoryPressured() {
+		const free = freemem();
+		if (free < MIN_FREE_MEMORY_BYTES) {
+			logger$12.warn({
+				freeMB: Math.round(free / 1024 / 1024),
+				thresholdMB: Math.round(MIN_FREE_MEMORY_BYTES / 1024 / 1024)
+			}, "Memory pressure detected — holding dispatch queue");
+			return true;
+		}
+		return false;
+	}
+	_startMemoryPressureTimer() {
+		if (this._memoryPressureTimer !== null) return;
+		this._memoryPressureTimer = setInterval(() => {
+			this._drainQueue();
+		}, MEMORY_PRESSURE_POLL_MS);
+		this._memoryPressureTimer.unref();
+	}
+	_stopMemoryPressureTimer() {
+		if (this._memoryPressureTimer !== null) {
+			clearInterval(this._memoryPressureTimer);
+			this._memoryPressureTimer = null;
+		}
+	}
 };
 /**
 * Create a new Dispatcher instance.
@@ -3866,8 +3958,11 @@ const DEFAULT_VITEST_PATTERNS = `## Test Patterns (defaults)
 - Mock approach: vi.mock() with hoisting for module-level mocks
 - Assertion style: expect().toBe(), expect().toEqual(), expect().toThrow()
 - Test structure: describe/it blocks with beforeEach/afterEach
-- Coverage: 80% enforced — run full suite, not filtered
-- Run tests: npm test 2>&1 | grep -E "Test Files|Tests " | tail -3`;
+- Coverage: 80% enforced
+- IMPORTANT: During development, run ONLY your relevant tests to save memory:
+  npx vitest run --no-coverage -- "your-module-name"
+- Final validation ONLY: npm test 2>&1 | grep -E "Test Files|Tests " | tail -3
+- Do NOT run the full suite (npm test) repeatedly — it consumes excessive memory when multiple agents run in parallel`;
 /**
 * Execute the compiled dev-story workflow.
 *
@@ -6247,16 +6342,43 @@ function createArtifactExistsGate(phase, artifactType) {
 }
 async function noOp(_db, _runId) {}
 /**
+* Create the Research phase definition.
+*
+* Entry gates: empty array (research is always the pipeline entrypoint when enabled)
+* Exit gates: 'research-findings' artifact must exist for this run
+*
+* This phase is inserted before analysis when research is enabled in the pack
+* manifest (`research: true`) or via the `--research` CLI flag.
+*/
+function createResearchPhaseDefinition() {
+	return {
+		name: "research",
+		description: "Conduct pre-analysis research: market landscape, competitive analysis, technical feasibility, and synthesized findings.",
+		entryGates: [],
+		exitGates: [createArtifactExistsGate("research", "research-findings")],
+		onEnter: async (_db, runId) => {
+			logPhase(`Research phase starting for run ${runId}`);
+		},
+		onExit: async (db, runId) => {
+			const artifact = getArtifactByTypeForRun(db, runId, "research", "research-findings");
+			if (artifact === void 0) logPhase(`Research phase exit WARNING: research-findings artifact not found for run ${runId}`);
+			else logPhase(`Research phase completed for run ${runId} — research-findings artifact registered: ${artifact.id}`);
+		}
+	};
+}
+/**
 * Create the Analysis phase definition.
 *
-* Entry gates: none (first phase — always can be entered)
+* Entry gates: none by default (first phase — always can be entered);
+*              when research is enabled, requires 'research-findings' artifact
 * Exit gates: 'product-brief' artifact must exist for this run
 */
-function createAnalysisPhaseDefinition() {
+function createAnalysisPhaseDefinition(options) {
+	const entryGates = options?.requiresResearch === true ? [createArtifactExistsGate("research", "research-findings")] : [];
 	return {
 		name: "analysis",
 		description: "Analyze the user concept and produce a product brief capturing requirements, constraints, and goals.",
-		entryGates: [],
+		entryGates,
 		exitGates: [createArtifactExistsGate("analysis", "product-brief")],
 		onEnter: async (_db, runId) => {
 			logPhase(`Analysis phase starting for run ${runId}`);
@@ -6371,13 +6493,19 @@ function createImplementationPhaseDefinition() {
 /**
 * Return the built-in phase definitions in execution order.
 *
+* When `researchEnabled` is true, the `research` phase is inserted at position 0
+* (before analysis), and the analysis phase gains a `research-findings` entry gate.
+*
 * When `uxDesignEnabled` is true, the `ux-design` phase is inserted between
 * `planning` and `solutioning`, with its own entry/exit gates.
 *
 * @param config - Optional configuration for conditional phase inclusion
 */
 function createBuiltInPhases(config) {
-	const phases = [createAnalysisPhaseDefinition(), createPlanningPhaseDefinition()];
+	const phases = [];
+	if (config?.researchEnabled === true) phases.push(createResearchPhaseDefinition());
+	phases.push(createAnalysisPhaseDefinition({ requiresResearch: config?.researchEnabled === true }));
+	phases.push(createPlanningPhaseDefinition());
 	if (config?.uxDesignEnabled === true) phases.push(createUxDesignPhaseDefinition());
 	phases.push(createSolutioningPhaseDefinition());
 	phases.push(createImplementationPhaseDefinition());
@@ -6444,8 +6572,12 @@ var PhaseOrchestratorImpl = class {
 		this._db = deps.db;
 		this._pack = deps.pack;
 		this._qualityGates = deps.qualityGates;
+		const researchEnabled = this._pack.manifest.research === true;
 		const uxDesignEnabled = this._pack.manifest.uxDesign === true;
-		this._phases = createBuiltInPhases({ uxDesignEnabled });
+		this._phases = createBuiltInPhases({
+			researchEnabled,
+			uxDesignEnabled
+		});
 		const builtInNames = new Set(this._phases.map((p) => p.name));
 		const packPhases = this._pack.getPhases();
 		for (const packPhase of packPhases) if (!builtInNames.has(packPhase.name)) this._phases.push({
@@ -6762,7 +6894,8 @@ function getCritiquePromptName(phase) {
 		planning: "critique-planning",
 		solutioning: "critique-architecture",
 		architecture: "critique-architecture",
-		stories: "critique-stories"
+		stories: "critique-stories",
+		research: "critique-research"
 	};
 	return mapping[phase] ?? `critique-${phase}`;
 }
@@ -7408,6 +7541,31 @@ const UxJourneysOutputSchema = z.object({
 	accessibility_guidelines: z.array(z.string()).default([])
 });
 /**
+* Step 1 output: Research Discovery.
+* Covers concept classification and raw findings across market, domain, and technical dimensions.
+* Content fields are optional to allow `{result: 'failed'}` without Zod rejection.
+*/
+const ResearchDiscoveryOutputSchema = z.object({
+	result: z.enum(["success", "failed"]),
+	concept_classification: z.string().optional(),
+	market_findings: z.string().optional(),
+	domain_findings: z.string().optional(),
+	technical_findings: z.string().optional()
+});
+/**
+* Step 2 output: Research Synthesis.
+* Covers distilled research findings, risk flags, and opportunity signals.
+* Content fields are optional to allow `{result: 'failed'}` without Zod rejection.
+*/
+const ResearchSynthesisOutputSchema = z.object({
+	result: z.enum(["success", "failed"]),
+	market_context: z.string().optional(),
+	competitive_landscape: z.string().optional(),
+	technical_feasibility: z.string().optional(),
+	risk_flags: z.array(z.string()).default([]),
+	opportunity_signals: z.array(z.string()).default([])
+});
+/**
 * Zod schema for the YAML output emitted by an elicitation sub-agent.
 * The agent returns structured insights from applying an elicitation method.
 */
@@ -9882,6 +10040,162 @@ async function runUxDesignPhase(deps, params) {
 	}
 }
 
+//#endregion
+//#region src/modules/phase-orchestrator/phases/research.ts
+/**
+* Build step definitions for 2-step research decomposition.
+*
+* Step 1: Discovery
+*   - Injects concept context
+*   - Produces: concept_classification, market_findings, domain_findings, technical_findings
+*
+* Step 2: Synthesis
+*   - Injects concept and Step 1 raw findings
+*   - Produces: market_context, competitive_landscape, technical_feasibility, risk_flags, opportunity_signals
+*   - Registers 'research-findings' artifact
+*/
+function buildResearchSteps() {
+	return [{
+		name: "research-step-1-discovery",
+		taskType: "research-discovery",
+		outputSchema: ResearchDiscoveryOutputSchema,
+		context: [{
+			placeholder: "concept",
+			source: "param:concept"
+		}],
+		persist: [
+			{
+				field: "concept_classification",
+				category: "research",
+				key: "concept_classification"
+			},
+			{
+				field: "market_findings",
+				category: "research",
+				key: "market_findings"
+			},
+			{
+				field: "domain_findings",
+				category: "research",
+				key: "domain_findings"
+			},
+			{
+				field: "technical_findings",
+				category: "research",
+				key: "technical_findings"
+			}
+		],
+		elicitate: true
+	}, {
+		name: "research-step-2-synthesis",
+		taskType: "research-synthesis",
+		outputSchema: ResearchSynthesisOutputSchema,
+		context: [{
+			placeholder: "concept",
+			source: "param:concept"
+		}, {
+			placeholder: "raw_findings",
+			source: "step:research-step-1-discovery"
+		}],
+		persist: [
+			{
+				field: "market_context",
+				category: "research",
+				key: "market_context"
+			},
+			{
+				field: "competitive_landscape",
+				category: "research",
+				key: "competitive_landscape"
+			},
+			{
+				field: "technical_feasibility",
+				category: "research",
+				key: "technical_feasibility"
+			},
+			{
+				field: "risk_flags",
+				category: "research",
+				key: "risk_flags"
+			},
+			{
+				field: "opportunity_signals",
+				category: "research",
+				key: "opportunity_signals"
+			}
+		],
+		registerArtifact: {
+			type: "research-findings",
+			path: "decision-store://research/research-findings",
+			summarize: (parsed) => {
+				const risks = Array.isArray(parsed.risk_flags) ? parsed.risk_flags : void 0;
+				const opportunities = Array.isArray(parsed.opportunity_signals) ? parsed.opportunity_signals : void 0;
+				const count = (risks?.length ?? 0) + (opportunities?.length ?? 0);
+				return count > 0 ? `${count} research insights captured (risks + opportunities)` : "Research synthesis complete";
+			}
+		},
+		critique: true
+	}];
+}
+/**
+* Execute the research phase of the BMAD pipeline.
+*
+* Runs 2 sequential steps covering discovery and synthesis.
+* Each step builds on prior step decisions via the decision store.
+*
+* On success, a 'research-findings' artifact is registered and research decisions
+* are available to subsequent phases via `decision:research.*`.
+*
+* @param deps - Shared phase dependencies (db, pack, contextCompiler, dispatcher)
+* @param params - Phase parameters (runId, concept)
+* @returns ResearchResult with success/failure status and token usage
+*/
+async function runResearchPhase(deps, params) {
+	const { runId } = params;
+	const zeroTokenUsage = {
+		input: 0,
+		output: 0
+	};
+	try {
+		const steps = buildResearchSteps();
+		const result = await runSteps(steps, deps, runId, "research", { concept: params.concept });
+		if (!result.success) return {
+			result: "failed",
+			error: result.error ?? "research_multi_step_failed",
+			details: result.error ?? "Research multi-step execution failed",
+			tokenUsage: result.tokenUsage
+		};
+		const lastStep = result.steps[result.steps.length - 1];
+		const artifactId = lastStep?.artifactId;
+		if (!artifactId) {
+			const artifact = registerArtifact(deps.db, {
+				pipeline_run_id: runId,
+				phase: "research",
+				type: "research-findings",
+				path: "decision-store://research/research-findings",
+				summary: "Research phase completed"
+			});
+			return {
+				result: "success",
+				artifact_id: artifact.id,
+				tokenUsage: result.tokenUsage
+			};
+		}
+		return {
+			result: "success",
+			artifact_id: artifactId,
+			tokenUsage: result.tokenUsage
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			result: "failed",
+			error: message,
+			tokenUsage: zeroTokenUsage
+		};
+	}
+}
+
 //#endregion
 //#region src/cli/commands/run.ts
 const logger = createLogger("run-cmd");
@@ -9901,7 +10215,7 @@ function mapInternalPhaseToEventPhase(internalPhase) {
 	}
 }
 async function runRunAction(options) {
-	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx } = options;
+	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag } = options;
 	if (startPhase !== void 0 && !VALID_PHASES.includes(startPhase)) {
 		const errorMsg = `Invalid phase '${startPhase}'. Valid phases: ${VALID_PHASES.join(", ")}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -9957,7 +10271,9 @@ async function runRunAction(options) {
 		outputFormat,
 		projectRoot,
 		...eventsFlag === true ? { events: true } : {},
-		...skipUx === true ? { skipUx: true } : {}
+		...skipUx === true ? { skipUx: true } : {},
+		...researchFlag === true ? { research: true } : {},
+		...skipResearchFlag === true ? { skipResearch: true } : {}
 	});
 	let storyKeys = [];
 	if (storiesArg !== void 0 && storiesArg !== "") {
@@ -10318,7 +10634,7 @@ async function runRunAction(options) {
 		else failedKeys.push(key);
 		try {
 			const runEndMs = Date.now();
-			const runStartMs = new Date(pipelineRun.created_at).getTime();
+			const runStartMs = parseDbTimestampAsUtc(pipelineRun.created_at).getTime();
 			const tokenAgg = aggregateTokenUsageForRun(db, pipelineRun.id);
 			const storyMetrics = getStoryMetricsForRun(db, pipelineRun.id);
 			const totalReviewCycles = storyMetrics.reduce((sum, m) => sum + (m.review_cycles ?? 0), 0);
@@ -10397,7 +10713,7 @@ async function runRunAction(options) {
 	}
 }
 async function runFullPipeline(options) {
-	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx } = options;
+	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag } = options;
 	if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 	const dbWrapper = new DatabaseWrapper(dbPath);
 	try {
@@ -10437,13 +10753,19 @@ async function runFullPipeline(options) {
 			contextCompiler,
 			dispatcher
 		};
-		const packForOrchestrator = skipUx === true && pack.manifest.uxDesign === true ? {
+		let effectiveResearch = pack.manifest.research === true;
+		if (researchFlag === true) effectiveResearch = true;
+		if (skipResearchFlag === true) effectiveResearch = false;
+		let effectiveUxDesign = pack.manifest.uxDesign === true;
+		if (skipUx === true) effectiveUxDesign = false;
+		const packForOrchestrator = {
 			...pack,
 			manifest: {
 				...pack.manifest,
-				uxDesign: false
+				research: effectiveResearch,
+				uxDesign: effectiveUxDesign
 			}
-		} : pack;
+		};
 		const phaseOrchestrator = createPhaseOrchestrator({
 			db,
 			pack: packForOrchestrator
@@ -10454,19 +10776,11 @@ async function runFullPipeline(options) {
 			process.stdout.write(`Starting full pipeline from phase: ${startPhase}\n`);
 			process.stdout.write(`Pipeline run ID: ${runId}\n`);
 		}
-		const uxEnabled = packForOrchestrator.manifest.uxDesign === true;
-		const phaseOrder = uxEnabled ? [
-			"analysis",
-			"planning",
-			"ux-design",
-			"solutioning",
-			"implementation"
-		] : [
-			"analysis",
-			"planning",
-			"solutioning",
-			"implementation"
-		];
+		const phaseOrder = [];
+		if (effectiveResearch) phaseOrder.push("research");
+		phaseOrder.push("analysis", "planning");
+		if (effectiveUxDesign) phaseOrder.push("ux-design");
+		phaseOrder.push("solutioning", "implementation");
 		const startIdx = phaseOrder.indexOf(startPhase);
 		for (let i = startIdx; i < phaseOrder.length; i++) {
 			const currentPhase = phaseOrder[i];
@@ -10520,6 +10834,32 @@ async function runFullPipeline(options) {
 					process.stdout.write(`[PLANNING] Complete — ${result.requirements_count ?? 0} requirements, ${result.user_stories_count ?? 0} user stories\n`);
 					process.stdout.write(`  Tokens: ${result.tokenUsage.input.toLocaleString()} input / ${result.tokenUsage.output.toLocaleString()} output\n`);
 				}
+			} else if (currentPhase === "research") {
+				const result = await runResearchPhase(phaseDeps, {
+					runId,
+					concept: concept ?? ""
+				});
+				if (result.tokenUsage.input > 0 || result.tokenUsage.output > 0) {
+					const costUsd = (result.tokenUsage.input * 3 + result.tokenUsage.output * 15) / 1e6;
+					addTokenUsage(db, runId, {
+						phase: "research",
+						agent: "claude-code",
+						input_tokens: result.tokenUsage.input,
+						output_tokens: result.tokenUsage.output,
+						cost_usd: costUsd
+					});
+				}
+				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
+					const errorMsg = `Research phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
+					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
+					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
+					return 1;
+				}
+				if (outputFormat === "human") {
+					process.stdout.write(`[RESEARCH] Complete — research findings artifact registered (artifact: ${result.artifact_id ?? "n/a"})\n`);
+					process.stdout.write(`  Tokens: ${result.tokenUsage.input.toLocaleString()} input / ${result.tokenUsage.output.toLocaleString()} output\n`);
+				}
 			} else if (currentPhase === "ux-design") {
 				const result = await runUxDesignPhase(phaseDeps, { runId });
 				if (result.tokenUsage.input > 0 || result.tokenUsage.output > 0) {
@@ -10684,7 +11024,7 @@ async function runFullPipeline(options) {
 	}
 }
 function registerRunCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
-	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").action(async (opts) => {
+	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 2).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").action(async (opts) => {
 		if (opts.helpAgent) {
 			process.exitCode = await runHelpAgent();
 			return;
@@ -10714,12 +11054,14 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 			events: opts.events,
 			verbose: opts.verbose,
 			tui: opts.tui,
-			skipUx: opts.skipUx
+			skipUx: opts.skipUx,
+			research: opts.research,
+			skipResearch: opts.skipResearch
 		});
 		process.exitCode = exitCode;
 	});
 }
 
 //#endregion
-export { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-D3ZscMlL.js.map
+export { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
+//# sourceMappingURL=run-0IlA2ubQ.js.map