substrate-ai 0.2.5 → 0.2.7

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import { createLogger, deepMask } from "../logger-C6n1g8uP.js";
 import { AdapterRegistry, createEventBus } from "../event-bus-J-bw-pkp.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "../version-manager-impl-BpVx2DkY.js";
-import { 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, runSolutioningPhase, validateStopAfterFromConflict } from "../run-CDYE1PT3.js";
+import { 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, runSolutioningPhase, validateStopAfterFromConflict } from "../run-CTOLQ2MR.js";
 import { ConfigError, ConfigIncompatibleFormatError } from "../errors-BPqtzQ4U.js";
 import { addTokenUsage, createDecision, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-DNYByk0U.js";
 import { aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
@@ -2833,7 +2833,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-XkrV99HV.js"
+									"../run-BaBWZUaK.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

package/dist/{run-XkrV99HV.js → run-BaBWZUaK.js}

@@ -1,6 +1,6 @@
 import "./logger-C6n1g8uP.js";
 import "./event-bus-J-bw-pkp.js";
-import { registerRunCommand, runRunAction } from "./run-CDYE1PT3.js";
+import { registerRunCommand, runRunAction } from "./run-CTOLQ2MR.js";
 import "./decisions-DNYByk0U.js";
 import "./metrics-BSg8VIHd.js";
 

package/dist/{run-CDYE1PT3.js → run-CTOLQ2MR.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";
 
@@ -2840,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;
@@ -2860,6 +2863,7 @@ var DispatcherImpl = class {
 	_running = new Map();
 	_queue = [];
 	_shuttingDown = false;
+	_memoryPressureTimer = null;
 	constructor(eventBus, adapterRegistry, config) {
 		this._eventBus = eventBus;
 		this._adapterRegistry = adapterRegistry;
@@ -2874,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);
@@ -2935,6 +2939,7 @@ var DispatcherImpl = class {
 	}
 	async shutdown() {
 		this._shuttingDown = true;
+		this._stopMemoryPressureTimer();
 		logger$12.info({
 			running: this._running.size,
 			queued: this._queue.length
@@ -3005,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, {
@@ -3211,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";
@@ -3227,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.
@@ -3920,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.
 *
@@ -6301,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}`);
@@ -6425,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());
@@ -6498,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({
@@ -6816,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}`;
 }
@@ -7462,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.
 */
@@ -9936,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");
@@ -9955,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");
@@ -10011,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 !== "") {
@@ -10451,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 {
@@ -10491,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
@@ -10508,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];
@@ -10574,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) {
@@ -10738,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), 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").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;
@@ -10768,7 +11054,9 @@ 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;
 	});
@@ -10776,4 +11064,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#endregion
 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-CDYE1PT3.js.map
+//# sourceMappingURL=run-CTOLQ2MR.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",

package/packs/bmad/manifest.yaml

@@ -2,12 +2,37 @@ name: bmad
 version: 1.0.0
 description: BMAD methodology for autonomous software development
 
+# Optional research phase (Story 20.1).
+# When true, a 'research' phase runs before analysis, conducting market/competitive research.
+# Set to false (or omit) to skip research and proceed directly to analysis.
+research: true
+
 # Optional UX design phase (Story 16.5).
 # When true, a 'ux-design' phase runs between planning and solutioning.
 # Set to false (or omit) to skip UX design and proceed directly to solutioning.
 uxDesign: true
 
 phases:
+  - name: research
+    description: Market research, competitive landscape analysis, and technical feasibility (runs before analysis when research is enabled)
+    entryGates: []
+    exitGates: [research-complete]
+    artifacts: [research-findings]
+    steps:
+      - name: research-step-1-discovery
+        template: research-step-1-discovery
+        context:
+          - placeholder: concept
+            source: "param:concept"
+        elicitate: true
+      - name: research-step-2-synthesis
+        template: research-step-2-synthesis
+        context:
+          - placeholder: concept
+            source: "param:concept"
+          - placeholder: raw_findings
+            source: "step:research-step-1-discovery"
+        critique: true
   - name: analysis
     description: Product discovery and brief creation
     entryGates: []
@@ -19,6 +44,8 @@ phases:
         context:
           - placeholder: concept
             source: "param:concept"
+          - placeholder: research_findings
+            source: "decision:research.findings"
         elicitate: true
       - name: analysis-step-2-scope
         template: analysis-step-2-scope
@@ -175,6 +202,10 @@ prompts:
   architecture-step-3-patterns: prompts/architecture-step-3-patterns.md
   stories-step-1-epics: prompts/stories-step-1-epics.md
   stories-step-2-stories: prompts/stories-step-2-stories.md
+  # Research phase prompts (Story 20-2)
+  research-step-1-discovery: prompts/research-step-1-discovery.md
+  research-step-2-synthesis: prompts/research-step-2-synthesis.md
+  critique-research: prompts/critique-research.md
   # UX design step prompts (Story 16-5)
   ux-step-1-discovery: prompts/ux-step-1-discovery.md
   ux-step-2-design-system: prompts/ux-step-2-design-system.md

package/packs/bmad/prompts/analysis-step-1-vision.md

@@ -5,12 +5,17 @@
 ### Project Concept
 {{concept}}
 
+### Research Context
+{{research_findings}}
+
 ---
 
 ## Mission
 
 Analyze the project concept above and produce a focused **vision analysis**: a clear problem statement and identification of target users. Do NOT define features or metrics yet — those come in a subsequent step.
 
+When Research Context is provided above, ground your vision analysis in that evidence: reference specific market signals, competitive gaps, or feasibility findings to justify your problem statement and user segmentation. When Research Context is empty, proceed using the concept alone — output quality must be identical.
+
 ## Instructions
 
 1. **Analyze the concept deeply:**

package/packs/bmad/prompts/critique-research.md

@@ -0,0 +1,92 @@
+# BMAD Critique Agent — Research Phase
+
+## Artifact Under Review
+
+{{artifact_content}}
+
+## Project Context
+
+{{project_context}}
+
+---
+
+## Your Role
+
+You are an adversarial quality reviewer. Your job is to find what's wrong with this research document before the team builds a product brief on a flawed foundation.
+
+Adopt a critical mindset: assume the research is incomplete, biased, or stale until proven otherwise.
+
+---
+
+## Quality Standards for Research Artifacts
+
+A high-quality research artifact must satisfy ALL of these criteria:
+
+### 1. Source Credibility
+- Findings must reference identifiable, credible sources (industry reports, named companies, published standards, or well-known open source projects).
+- Vague attributions like "industry experts say" or "research shows" without specifics are unacceptable.
+- Market sizing claims must include a source or methodology (e.g., "Gartner 2024", "company 10-K", "author's estimate based on TAM").
+- At minimum, 2-3 named companies or products must be referenced as evidence.
+
+### 2. Finding Relevance
+- Every finding must be directly relevant to the stated concept — tangential observations about adjacent markets are noise.
+- Market findings must describe the actual target buyer, not a proxy audience.
+- Technical findings must reflect the technology decisions the concept will actually face, not hypothetical stacks.
+- Risk flags must be specific and actionable (not generic "the market is competitive").
+
+### 3. Gap Identification
+- The research must acknowledge what it does NOT know — gaps are acceptable, but must be named explicitly.
+- If web search was unavailable, the agent must state that findings are based on training knowledge and may be stale.
+- Missing dimensions: if any of market, competitive, technical, or risk analysis is absent, it is a blocker.
+- Opportunity signals must be grounded in research — speculative "we could do X" signals are unacceptable.
+
+### 4. Synthesis Coherence
+- The competitive landscape must identify named competitors, not generic categories ("some incumbents").
+- Risk flags must be distinct from each other — no duplicates or slight rewording of the same risk.
+- Opportunity signals must logically follow from the findings — they must be traceable to specific evidence in the research.
+- Market context and competitive landscape must be internally consistent — contradictions are blockers.
+
+---
+
+## Instructions
+
+1. Read the artifact carefully. Do not assume anything is correct.
+2. For each quality dimension above, identify whether it is met, partially met, or missing.
+3. For each issue found, classify its severity:
+   - **blocker**: The research cannot be used to proceed — a critical dimension is missing, contradictory, or completely uncredible.
+   - **major**: Significant quality gap that will bias the product brief if not addressed.
+   - **minor**: Improvement that would increase quality but does not block progress.
+
+4. If the artifact meets all criteria, emit a `pass` verdict with zero issues.
+
+---
+
+## Output Contract
+
+Emit ONLY this YAML block — no preamble, no explanation, no other text.
+
+If no issues found:
+
+```yaml
+verdict: pass
+issue_count: 0
+issues: []
+```
+
+If issues found:
+
+```yaml
+verdict: needs_work
+issue_count: 2
+issues:
+  - severity: major
+    category: source-credibility
+    description: "Market size claim of '$15B by 2027' has no cited source or methodology."
+    suggestion: "Add the source (e.g., 'per Gartner 2024 Cloud Infrastructure Report') or note it as an author estimate with the derivation method."
+  - severity: minor
+    category: finding-relevance
+    description: "Technical findings describe a microservices architecture that is not relevant to the stated single-tenant SaaS concept."
+    suggestion: "Replace with findings specific to single-tenant deployment patterns, data isolation models, and per-tenant customization approaches."
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.

package/packs/bmad/prompts/research-step-1-discovery.md

@@ -0,0 +1,76 @@
+# BMAD Research Step 1: Discovery
+
+## Context (pre-assembled by pipeline)
+
+### Concept
+{{concept}}
+
+---
+
+## Mission
+
+Conduct a thorough **research discovery** for this concept. Your goal is to gather and organize raw findings across three dimensions:
+
+1. **Concept Classification** — what type of product or tool is this, who is it for, and what domain does it operate in?
+2. **Market Findings** — market size, target customers, pricing models, and market trends
+3. **Domain Findings** — best practices, industry standards, regulatory requirements, and use cases
+4. **Technical Findings** — technical architecture patterns, technology stacks, open source alternatives, and implementation challenges
+
+This raw discovery output will feed directly into a synthesis step that distills the findings into actionable insights.
+
+## Instructions
+
+### 1. Classify the Concept
+
+Before searching, classify the concept:
+- **Product type**: Is this a product sold to customers, or an internal tool / developer tooling?
+- **Industry vertical**: What industry or sector does it primarily serve (e.g., fintech, healthcare, devtools, SaaS platform, e-commerce)?
+- **Tech domain**: What is the primary technical domain (e.g., data pipelines, mobile apps, APIs, AI/ML, infrastructure)?
+
+### 2. Conduct Web Research
+
+Use web search to gather findings across the three dimensions below. Execute approximately 12 searches total — 3-4 per dimension.
+
+**Market dimension queries:**
+- `"{{concept}} market size"`
+- `"{{concept}} target customers"`
+- `"{{concept}} pricing models"`
+- `"{{concept}} market trends 2025"`
+
+**Domain dimension queries:**
+- `"{{concept}} best practices"`
+- `"{{concept}} industry standards"`
+- `"{{concept}} regulatory requirements"`
+- `"{{concept}} use cases"`
+
+**Technical dimension queries:**
+- `"{{concept}} technical architecture"`
+- `"{{concept}} technology stack"`
+- `"{{concept}} open source alternatives"`
+- `"{{concept}} implementation challenges"`
+
+> **Fallback**: If web search is unavailable in your environment, proceed with concept analysis using your training knowledge — acknowledge that findings may not reflect the latest market conditions.
+
+### 3. Organize Findings
+
+For each dimension, summarize the key findings in 2-4 sentences. Be specific: name actual companies, technologies, standards, or regulations where found. Avoid vague generalizations.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text, no preamble.
+
+**CRITICAL**: All string values MUST be quoted with double quotes.
+
+```yaml
+result: success
+concept_classification: "B2B SaaS product targeting mid-market DevOps teams in the cloud infrastructure space"
+market_findings: "The cloud infrastructure automation market is valued at $12B in 2024, growing at 18% CAGR. Primary customers are platform engineering teams at companies with 50-500 engineers. Pricing models cluster around per-seat ($30-80/month) and usage-based (per compute hour). Key trend: shift from IaaS to developer-experience platforms."
+domain_findings: "Industry standards include Terraform HCL for IaC and GitOps workflows (CNCF). Regulatory requirements vary by industry: SOC 2 Type II is table stakes for enterprise; HIPAA for healthcare customers. Key use cases: multi-cloud deployment, drift detection, cost optimization, and compliance reporting."
+technical_findings: "Dominant architectural pattern is event-driven with a control plane / data plane separation. Common stack: Go or Rust for the agent, React for dashboard, PostgreSQL + TimescaleDB for time-series data. Open source alternatives include Pulumi, OpenTofu, and Crossplane. Primary implementation challenges are state reconciliation under network partitions and secret management at scale."
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/research-step-2-synthesis.md

@@ -0,0 +1,64 @@
+# BMAD Research Step 2: Synthesis
+
+## Context (pre-assembled by pipeline)
+
+### Concept
+{{concept}}
+
+### Raw Research Findings
+{{raw_findings}}
+
+---
+
+## Mission
+
+Synthesize the raw research findings into a structured, actionable research report. Your goal is to distill the discovery output into five key sections:
+
+1. **Market Context** — the market landscape, sizing, and customer dynamics
+2. **Competitive Landscape** — who the key competitors are, their positioning, and differentiation opportunities
+3. **Technical Feasibility** — how technically viable this concept is, key technology choices, and build vs. buy considerations
+4. **Risk Flags** — specific risks that could threaten success (market, technical, regulatory, execution)
+5. **Opportunity Signals** — specific indicators of where this concept has an advantage or untapped potential
+
+This synthesis output feeds directly into the analysis phase to ground the product brief in real-world context.
+
+## Instructions
+
+1. **Market Context**: Synthesize the market dimension findings. Quantify the opportunity where possible. Identify the primary buyer profile and decision-maker. Note any market timing signals (growing, contracting, consolidating).
+
+2. **Competitive Landscape**: Identify named competitors (direct and adjacent). Describe how they are positioned. Identify gaps or differentiation opportunities that the concept could exploit.
+
+3. **Technical Feasibility**: Assess how technically achievable the concept is given the technology landscape. Highlight proven patterns to adopt, and identify areas where the technical approach is risky or unproven.
+
+4. **Risk Flags**: List 3-6 specific, concrete risks. Each risk should name the threat and its potential impact. Avoid generic risks like "execution risk" — be specific (e.g., "Compliance with HIPAA BAA requirements may add 3-6 months to enterprise sales cycles").
+
+5. **Opportunity Signals**: List 3-6 specific indicators that suggest this concept has real potential. These should be grounded in the research findings, not wishful thinking.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text, no preamble.
+
+**CRITICAL**: All string values MUST be quoted with double quotes. List items in `risk_flags` and `opportunity_signals` must also be double-quoted.
+
+```yaml
+result: success
+market_context: "The cloud infrastructure automation market is a $12B opportunity growing at 18% CAGR, driven by the shift from DevOps to platform engineering. Primary buyers are VPs of Engineering and Platform Engineering leads at Series B+ startups and mid-market companies. Market is in early growth phase with high willingness to pay for workflow automation."
+competitive_landscape: "Direct competitors are Terraform Cloud (HashiCorp/IBM), Spacelift, and Scalr — all targeting the same DevOps persona. Pulumi competes on developer experience with a code-first approach. Differentiation opportunity: none of the incumbent tools offer AI-assisted drift detection or natural-language policy authoring. Open source (OpenTofu) commoditizes the IaC layer, making the control plane the primary value surface."
+technical_feasibility: "High feasibility using proven patterns: Go agent with event-driven control plane (used by Argo CD, Flux), React dashboard, and PostgreSQL for state. Primary technical risk is distributed state reconciliation under network partitions. Build recommendation: agent core in Go, leverage existing Terraform/OpenTofu compatibility, avoid building a custom DSL."
+risk_flags:
+  - "Regulatory: HIPAA and SOC 2 Type II compliance are table stakes for enterprise sales — adds 4-6 months to first enterprise close"
+  - "Competitive: HashiCorp's BSL license change accelerated OpenTofu adoption — if IBM reverses the decision, momentum could shift back"
+  - "Technical: Distributed state reconciliation under network partitions is an unsolved problem that all incumbents struggle with — high engineering cost"
+  - "Market: Per-seat pricing erodes at scale (>500 engineers) — customers will demand volume discounts or switch to usage-based pricing"
+opportunity_signals:
+  - "AI-native workflows: no incumbent offers natural-language policy authoring or AI-assisted remediation — clear whitespace"
+  - "OpenTofu migration wave: 30%+ of Terraform users are evaluating alternatives following the BSL license change — timing is favorable"
+  - "Platform engineering trend: Gartner predicts 80% of large orgs will have platform engineering teams by 2026 — growing buyer segment"
+  - "Developer experience gap: incumbent UIs are functional but dated — a modern, keyboard-first interface is a differentiator"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```