@substrate-ai/sdlc 0.19.54

package/dist/handlers/sdlc-dev-story-handler.js

@@ -0,0 +1,288 @@
+/**
+ * SdlcDevStoryHandler — wraps the runDevStory compiled workflow
+ * as a graph NodeHandler for sdlc.dev-story nodes.
+ *
+ * Story 43-4.
+ *
+ * Architecture note (ADR-003): The SDLC package does not compile-time-depend on
+ * @substrate-ai/factory to avoid circular references. Compatible types are
+ * defined locally using TypeScript structural typing — they are assignable to
+ * the factory types when the CLI composition root wires them together at runtime.
+ */
+import { readFileSync } from 'node:fs';
+import { classifyAndPersist } from '../learning/finding-classifier.js';
+import { FindingsInjector, extractTargetFilesFromStoryContent } from '../learning/findings-injector.js';
+import { FindingLifecycleManager } from '../learning/finding-lifecycle.js';
+import { DispatchGate } from '../gating/dispatch-gate.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an sdlc.dev-story node handler.
+ *
+ * The returned handler:
+ *   1. Validates storyKey and storyFilePath are present in GraphContext (AC6)
+ *   2. Reads optional retry remediation context from prior iteration (AC4)
+ *   3. Injects relevant prior-run findings into dispatch params (Story 53-8 AC2)
+ *   4. Emits orchestrator:story-phase-start telemetry (AC5)
+ *   5. Delegates to runDevStory(deps, params) (AC1)
+ *   6. Emits orchestrator:story-phase-complete telemetry in finally block (AC5)
+ *   7. Maps the DevStoryResult to an Outcome (AC2, AC3)
+ *   8. On failure: classifyAndPersist + emit pipeline:finding-captured (Story 53-8 AC1, AC6)
+ *   9. On success: retireContradictedFindings (Story 53-8 AC4)
+ *
+ * @param options - Handler configuration.
+ * @returns A NodeHandler function ready for registration under the 'sdlc.dev-story' key.
+ */
+export function createSdlcDevStoryHandler(options) {
+    return async (_node, context, _graph) => {
+        // AC6: Validate required context keys before calling runDevStory
+        const storyKey = context.getString('storyKey', '');
+        const storyFilePath = context.getString('storyFilePath', '');
+        if (!storyKey || !storyFilePath) {
+            const missingFields = [
+                !storyKey && 'storyKey',
+                !storyFilePath && 'storyFilePath',
+            ].filter(Boolean);
+            return {
+                status: 'FAILURE',
+                failureReason: `Missing required context: ${missingFields.join(', ')}`,
+            };
+        }
+        // AC1: Extract optional pipelineRunId — omit key when absent
+        // (exactOptionalPropertyTypes requires optional fields to be absent, not undefined)
+        const pipelineRunIdRaw = context.getString('pipelineRunId', '');
+        // AC4: Read prior iteration remediation context from context
+        const priorFiles = context.getList?.('devStoryFilesModified') ?? [];
+        const priorAcFailures = context.getList?.('devStoryAcFailures') ?? [];
+        // ---------------------------------------------------------------------------
+        // Read story content (used for findings injection and dispatch gating)
+        // ---------------------------------------------------------------------------
+        let storyContent = '';
+        try {
+            storyContent = readFileSync(storyFilePath, 'utf-8');
+        }
+        catch {
+            // Non-fatal: if file can't be read, use empty content
+        }
+        // ---------------------------------------------------------------------------
+        // Story 53-8 AC2: Pre-dispatch findings injection
+        // ---------------------------------------------------------------------------
+        let findingsPrompt = '';
+        if (options.db != null) {
+            try {
+                // Infer packageName from storyKey prefix (e.g., '53-8' → no package, or from path)
+                const pkgMatch = /packages\/([^/]+)\//.exec(storyFilePath);
+                const packageName = pkgMatch?.[1];
+                const injectionCtx = {
+                    storyKey,
+                    runId: pipelineRunIdRaw !== '' ? pipelineRunIdRaw : 'unknown',
+                    targetFiles: extractTargetFilesFromStoryContent(storyContent),
+                    ...(packageName !== undefined ? { packageName } : {}),
+                };
+                findingsPrompt = await FindingsInjector.inject(options.db, injectionCtx);
+            }
+            catch {
+                // AC5: Non-fatal — DB errors must never block dispatch
+                console.warn('[sdlc-dev-story-handler] FindingsInjector.inject failed; proceeding without findings');
+                findingsPrompt = '';
+            }
+        }
+        // ---------------------------------------------------------------------------
+        // Story 53-9: Dispatch pre-condition gating
+        // Runs after findings injection, before agent dispatch.
+        // Non-fatal: any gate error is caught and dispatch proceeds normally.
+        // ---------------------------------------------------------------------------
+        if (options.db != null) {
+            try {
+                const pendingFiles = extractTargetFilesFromStoryContent(storyContent);
+                const gateOptions = {
+                    storyKey,
+                    storyContent,
+                    pendingFiles,
+                    // completedStories: populated from run manifest per_story_state.
+                    // Currently no modifiedFiles tracked in manifest — empty array is
+                    // correct (gate degrades gracefully per AC7). Learning pre-emption
+                    // (AC6) still functions via the DB query path.
+                    completedStories: [],
+                    db: options.db,
+                    projectRoot: process.cwd(),
+                };
+                const gateResult = await DispatchGate.check(gateOptions);
+                if (gateResult.decision === 'warn' && gateResult.overlappingFiles !== undefined && gateResult.completedStoryKey !== undefined) {
+                    // AC2: emit warning event; dispatch proceeds normally
+                    options.eventBus.emit('pipeline:dispatch-warn', {
+                        storyKey,
+                        completedStoryKey: gateResult.completedStoryKey,
+                        overlappingFiles: gateResult.overlappingFiles,
+                    });
+                }
+                else if (gateResult.decision === 'block' && gateResult.modifiedPrompt !== undefined) {
+                    // AC4: auto-resolved; extract extension note from modifiedPrompt and inject
+                    // into findingsPrompt so the agent receives the namespace extension guidance.
+                    // modifiedPrompt = storyContent + '\n\n' + extensionNote
+                    const extensionNote = gateResult.modifiedPrompt.slice(storyContent.length).trim();
+                    if (extensionNote.length > 0) {
+                        findingsPrompt = findingsPrompt !== ''
+                            ? `${findingsPrompt}\n\n${extensionNote}`
+                            : extensionNote;
+                    }
+                }
+                else if (gateResult.decision === 'gated') {
+                    // AC5: non-resolvable conflict; place story in gated phase
+                    options.eventBus.emit('pipeline:story-gated', {
+                        storyKey,
+                        conflictType: gateResult.conflictType ?? 'namespace-collision',
+                        reason: gateResult.reason ?? 'dispatch gate: non-resolvable conflict',
+                        ...(gateResult.completedStoryKey !== undefined
+                            ? { completedStoryKey: gateResult.completedStoryKey }
+                            : {}),
+                    });
+                    // Return early without dispatching — story stays in gated phase
+                    return {
+                        status: 'FAILURE',
+                        failureReason: gateResult.reason ?? 'dispatch gate: story gated — operator review required',
+                    };
+                }
+            }
+            catch {
+                // AC7: gate error must never block dispatch
+                console.debug('[sdlc-dev-story-handler] DispatchGate.check failed; proceeding with original dispatch');
+            }
+        }
+        // Build DevStoryParams with required + optional fields
+        const devStoryParams = {
+            storyKey,
+            storyFilePath,
+            ...(pipelineRunIdRaw !== '' ? { pipelineRunId: pipelineRunIdRaw } : {}),
+            // AC4: Pass accumulated modified files from prior iteration as priorFiles
+            ...(priorFiles.length > 0 ? { priorFiles } : {}),
+            // AC4: Construct taskScope note describing prior failures if present
+            ...(priorAcFailures.length > 0
+                ? { taskScope: `Prior attempt failed ACs: ${priorAcFailures.join(', ')}` }
+                : {}),
+            // Story 53-8 AC2 + Story 53-9 AC4: findings + gate extension note (if any)
+            ...(findingsPrompt !== '' ? { findingsPrompt } : {}),
+        };
+        // AC5: Emit phase-start telemetry before calling runDevStory
+        options.eventBus.emit('orchestrator:story-phase-start', {
+            storyKey,
+            phase: 'dev-story',
+            ...(pipelineRunIdRaw !== '' ? { pipelineRunId: pipelineRunIdRaw } : {}),
+        });
+        // Initialize outcome to a default so finally block always has a valid status
+        let outcome = { status: 'FAILURE', failureReason: 'unexpected error in dev-story handler' };
+        try {
+            // AC1: Delegate to runDevStory
+            const workflowResult = await options.runDevStory(options.deps, devStoryParams);
+            if (workflowResult.result === 'success') {
+                // Build verification gate: catch compile errors before code-review
+                if (options.buildVerifier) {
+                    const projectRoot = context.getString('projectRoot', '');
+                    if (projectRoot) {
+                        const buildResult = options.buildVerifier(projectRoot);
+                        if (buildResult.status === 'failed' || buildResult.status === 'timeout') {
+                            outcome = {
+                                status: 'FAILURE',
+                                failureReason: `build verification failed after dev-story: ${buildResult.output?.slice(0, 500) ?? 'no output'}`,
+                                contextUpdates: {
+                                    filesModified: workflowResult.files_modified,
+                                    devStoryFilesModified: workflowResult.files_modified,
+                                    devStoryAcFailures: ['build-verification'],
+                                },
+                            };
+                            return outcome;
+                        }
+                    }
+                }
+                // AC2: Map success result to SUCCESS Outcome with implementation artifacts
+                outcome = {
+                    status: 'SUCCESS',
+                    contextUpdates: {
+                        filesModified: workflowResult.files_modified,
+                        acMet: workflowResult.ac_met,
+                        // Persist for retry pass-through (AC4)
+                        devStoryFilesModified: workflowResult.files_modified,
+                    },
+                };
+                // ---------------------------------------------------------------------------
+                // Story 53-8 AC4: Retire contradicted findings on success
+                // ---------------------------------------------------------------------------
+                if (options.db != null) {
+                    const successCtx = {
+                        modifiedFiles: workflowResult.files_modified,
+                        runId: pipelineRunIdRaw !== '' ? pipelineRunIdRaw : 'unknown',
+                    };
+                    try {
+                        await FindingLifecycleManager.retireContradictedFindings(successCtx, options.db);
+                    }
+                    catch {
+                        // AC5: Non-fatal — DB errors must never block success outcome
+                        console.warn('[sdlc-dev-story-handler] retireContradictedFindings failed; continuing');
+                    }
+                }
+            }
+            else {
+                // AC3: Map failure result to FAILURE Outcome with remediation context
+                const failureReason = workflowResult.error ??
+                    (workflowResult.ac_failures.length > 0
+                        ? `dev-story failed ACs: ${workflowResult.ac_failures.join(', ')}`
+                        : 'dev-story workflow failed');
+                outcome = {
+                    status: 'FAILURE',
+                    failureReason,
+                    contextUpdates: {
+                        acFailures: workflowResult.ac_failures,
+                        filesModified: workflowResult.files_modified,
+                        // Persist for retry pass-through (AC4)
+                        devStoryFilesModified: workflowResult.files_modified,
+                        devStoryAcFailures: workflowResult.ac_failures,
+                    },
+                };
+                // ---------------------------------------------------------------------------
+                // Story 53-8 AC1: Classify and persist failure finding
+                // ---------------------------------------------------------------------------
+                if (options.db != null) {
+                    const failureCtx = {
+                        storyKey,
+                        runId: pipelineRunIdRaw !== '' ? pipelineRunIdRaw : 'unknown',
+                        // exactOptionalPropertyTypes: omit 'error' when undefined rather than set to undefined
+                        ...(workflowResult.error !== undefined ? { error: workflowResult.error } : {}),
+                        affectedFiles: workflowResult.files_modified,
+                        buildFailed: workflowResult.ac_failures.includes('build-verification'),
+                        testsFailed: workflowResult.tests === 'fail',
+                    };
+                    try {
+                        const finding = await classifyAndPersist(failureCtx, options.db);
+                        // AC6: Emit pipeline:finding-captured after successful persist
+                        options.eventBus.emit('pipeline:finding-captured', {
+                            storyKey,
+                            runId: failureCtx.runId,
+                            rootCause: finding.root_cause,
+                        });
+                    }
+                    catch {
+                        // AC5: Non-fatal — DB errors must never block failure outcome
+                        console.warn('[sdlc-dev-story-handler] classifyAndPersist failed; continuing');
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // Handle unexpected throws from runDevStory
+            const failureReason = err instanceof Error ? err.message : String(err);
+            outcome = { status: 'FAILURE', failureReason };
+        }
+        finally {
+            // AC5: Emit phase-complete in finally block — guaranteed even on throw
+            options.eventBus.emit('orchestrator:story-phase-complete', {
+                storyKey,
+                phase: 'dev-story',
+                result: { status: outcome.status },
+                ...(pipelineRunIdRaw !== '' ? { pipelineRunId: pipelineRunIdRaw } : {}),
+            });
+        }
+        return outcome;
+    };
+}
+//# sourceMappingURL=sdlc-dev-story-handler.js.map

package/dist/handlers/sdlc-dev-story-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdlc-dev-story-handler.js","sourceRoot":"","sources":["../../src/handlers/sdlc-dev-story-handler.ts"],"names":[],"mappings":"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"}

package/dist/handlers/sdlc-phase-handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SdlcPhaseHandler — wraps SDLC pipeline phase execution as a graph NodeHandler.
+ *
+ * Story 43-2.
+ *
+ * Architecture note (ADR-003): This package does not import from @substrate-ai/factory
+ * or from the monolith source tree at compile time. All external dependencies
+ * (orchestrator, phaseDeps, phase runner functions) are injected via
+ * SdlcPhaseHandlerDeps at construction time.
+ *
+ * TypeScript structural typing ensures the returned SdlcNodeHandler is
+ * assignable to NodeHandler from @substrate-ai/factory at the CLI composition
+ * root — no sdlc→factory import required.
+ */
+import type { SdlcPhaseHandlerDeps, SdlcNodeHandler } from './types.js';
+/**
+ * Create an sdlc.phase node handler.
+ *
+ * The returned handler:
+ *   1. Resolves the phase name from node.id (AC5)
+ *   2. Looks up the corresponding runner in the PHASE_RUNNERS map (AC7)
+ *   3. Calls the runner with phaseDeps and phase-specific params (AC1, AC2, AC5)
+ *   4. On runner error, returns FAILURE without re-throwing (AC3)
+ *   5. If advanceAfterRun !== false, calls orchestrator.advancePhase(runId) (AC4)
+ *   6. If gate check fails (advanced === false), returns FAILURE with gate messages (AC4)
+ *   7. On full success, returns SUCCESS with phase output in contextUpdates (AC1, AC2)
+ *
+ * @param deps - Injected dependencies: orchestrator, phaseDeps, phase runners.
+ * @returns A SdlcNodeHandler ready for registration under the 'sdlc.phase' key.
+ */
+export declare function createSdlcPhaseHandler(deps: SdlcPhaseHandlerDeps): SdlcNodeHandler;
+//# sourceMappingURL=sdlc-phase-handler.d.ts.map

package/dist/handlers/sdlc-phase-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdlc-phase-handler.d.ts","sourceRoot":"","sources":["../../src/handlers/sdlc-phase-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAe,MAAM,YAAY,CAAA;AAMpF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe,CAiKlF"}

package/dist/handlers/sdlc-phase-handler.js

@@ -0,0 +1,166 @@
+/**
+ * SdlcPhaseHandler — wraps SDLC pipeline phase execution as a graph NodeHandler.
+ *
+ * Story 43-2.
+ *
+ * Architecture note (ADR-003): This package does not import from @substrate-ai/factory
+ * or from the monolith source tree at compile time. All external dependencies
+ * (orchestrator, phaseDeps, phase runner functions) are injected via
+ * SdlcPhaseHandlerDeps at construction time.
+ *
+ * TypeScript structural typing ensures the returned SdlcNodeHandler is
+ * assignable to NodeHandler from @substrate-ai/factory at the CLI composition
+ * root — no sdlc→factory import required.
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an sdlc.phase node handler.
+ *
+ * The returned handler:
+ *   1. Resolves the phase name from node.id (AC5)
+ *   2. Looks up the corresponding runner in the PHASE_RUNNERS map (AC7)
+ *   3. Calls the runner with phaseDeps and phase-specific params (AC1, AC2, AC5)
+ *   4. On runner error, returns FAILURE without re-throwing (AC3)
+ *   5. If advanceAfterRun !== false, calls orchestrator.advancePhase(runId) (AC4)
+ *   6. If gate check fails (advanced === false), returns FAILURE with gate messages (AC4)
+ *   7. On full success, returns SUCCESS with phase output in contextUpdates (AC1, AC2)
+ *
+ * @param deps - Injected dependencies: orchestrator, phaseDeps, phase runners.
+ * @returns A SdlcNodeHandler ready for registration under the 'sdlc.phase' key.
+ */
+export function createSdlcPhaseHandler(deps) {
+    // Build the PHASE_RUNNERS map from the injected phase runner functions.
+    // Using a Map allows O(1) lookup and supports the unknown-phase check (AC7).
+    const PHASE_RUNNERS = new Map(Object.entries(deps.phases));
+    return async (node, context, _graph) => {
+        // AC5: Phase selection is driven by node.id
+        const phaseName = node.id;
+        // AC7: Unknown phase — no runner registered
+        const runner = PHASE_RUNNERS.get(phaseName);
+        if (runner === undefined) {
+            return {
+                status: 'FAILURE',
+                failureReason: `No phase runner registered for phase: ${phaseName}`,
+            };
+        }
+        // Extract context values
+        const runId = context.getString('runId');
+        // AC1: concept is only needed for the analysis phase
+        const concept = phaseName === 'analysis' ? context.getString('concept', '') : '';
+        // Story-key skip: when --stories is provided (explicit story dispatch), the linear
+        // engine skips analysis/planning/solutioning entirely. Mirror that behavior in the
+        // graph engine by checking for storyKey in context — its presence means we're
+        // targeting implementation directly and early phases should be skipped.
+        const PRE_IMPL_PHASES = ['analysis', 'planning', 'solutioning'];
+        const storyKey = context.getString('storyKey', '');
+        if (storyKey && PRE_IMPL_PHASES.includes(phaseName)) {
+            return {
+                status: 'SUCCESS',
+                notes: `Phase ${phaseName} skipped — explicit story dispatch (storyKey=${storyKey})`,
+            };
+        }
+        // Phase-skip check: if the phase's output artifact already exists (from a prior run or
+        // from the linear engine having completed it), skip dispatch and return SUCCESS.
+        // This gives the graph engine behavioral parity with the linear engine's detectStartPhase().
+        //
+        // When skipping, we also register the artifact(s) for the CURRENT pipeline run so that
+        // downstream entry gates (which filter by pipeline_run_id) can find them. Without this,
+        // the implementation phase's entry gate would fail because it only sees artifacts from
+        // the current run.
+        const PHASE_ARTIFACT_TYPES = {
+            analysis: ['product-brief'],
+            planning: ['prd'],
+            solutioning: ['architecture', 'stories'],
+        };
+        const artifactTypes = PHASE_ARTIFACT_TYPES[phaseName];
+        if (artifactTypes !== undefined) {
+            try {
+                const db = deps.phaseDeps.db;
+                if (db) {
+                    // Check if ALL required artifacts for this phase exist globally
+                    let allExist = true;
+                    for (const at of artifactTypes) {
+                        const rows = await db.query('SELECT id, path, content_hash, summary FROM artifacts WHERE phase = ? AND type = ? ORDER BY created_at DESC LIMIT 1', [phaseName, at]);
+                        if (!Array.isArray(rows) || rows.length === 0) {
+                            allExist = false;
+                            break;
+                        }
+                    }
+                    if (allExist) {
+                        // Register each artifact for the current pipeline run so downstream entry gates pass.
+                        // The pipelineRunId comes from context (set by the graph orchestrator).
+                        const pipelineRunId = context.getString('pipelineRunId', '');
+                        if (pipelineRunId) {
+                            for (const at of artifactTypes) {
+                                const existing = await db.query('SELECT id, path, content_hash, summary FROM artifacts WHERE phase = ? AND type = ? ORDER BY created_at DESC LIMIT 1', [phaseName, at]);
+                                const src = existing[0];
+                                if (src) {
+                                    // Check if we've already registered this for the current run
+                                    const alreadyRegistered = await db.query('SELECT id FROM artifacts WHERE pipeline_run_id = ? AND phase = ? AND type = ? LIMIT 1', [pipelineRunId, phaseName, at]);
+                                    if (!Array.isArray(alreadyRegistered) || alreadyRegistered.length === 0) {
+                                        const newId = crypto.randomUUID();
+                                        await db.query('INSERT INTO artifacts (id, pipeline_run_id, phase, type, path, content_hash, summary) VALUES (?, ?, ?, ?, ?, ?, ?)', [newId, pipelineRunId, phaseName, at, src.path, src.content_hash ?? null, src.summary ?? null]);
+                                    }
+                                }
+                            }
+                        }
+                        return {
+                            status: 'SUCCESS',
+                            notes: `Phase ${phaseName} already complete — artifact(s) exist, skipping dispatch`,
+                        };
+                    }
+                }
+            }
+            catch {
+                // DB query failed — proceed with normal dispatch (don't block on skip check failure)
+            }
+        }
+        // Build phase-specific params (analysis requires concept; others only runId)
+        const params = phaseName === 'analysis' ? { runId, concept } : { runId };
+        // Outer try/catch wraps the entry gate check, runner call, and advancePhase call.
+        // This boundary satisfies AC3 (runner error) and also handles the case
+        // where evaluateEntryGates or advancePhase itself throws (network/DB error).
+        try {
+            // Story 43-13 AC1, AC2, AC4: Evaluate entry gates before dispatching runner.
+            // evaluateEntryGates is always called regardless of advanceAfterRun flag.
+            const entryGateResult = await deps.orchestrator.evaluateEntryGates(runId);
+            if (!entryGateResult.passed) {
+                const failures = entryGateResult.failures
+                    ?.map((f) => `${f.gate}: ${f.error}`)
+                    .join('; ') ?? 'no details';
+                return { status: 'FAILURE', failureReason: `entry gate failed: ${failures}` };
+            }
+            // AC1, AC2, AC5: Dispatch to the registered phase runner
+            const phaseOutput = await runner(deps.phaseDeps, params);
+            // AC4: Advance phase unless the caller has disabled it
+            if (deps.advanceAfterRun !== false) {
+                const advanceResult = await deps.orchestrator.advancePhase(runId);
+                if (!advanceResult.advanced) {
+                    // Story 43-13 AC3, AC4: Exit gate failure — prefix with 'exit gate failed: '
+                    const failures = advanceResult.gateFailures
+                        ?.map((f) => `${f.gate}: ${f.error}`)
+                        .join('; ') ?? 'no details';
+                    return { status: 'FAILURE', failureReason: `exit gate failed: ${failures}` };
+                }
+                // AC1, AC2: Full success — include phase output and advanced phase name
+                return {
+                    status: 'SUCCESS',
+                    contextUpdates: { ...phaseOutput, advancedPhase: advanceResult.phase },
+                };
+            }
+            // advanceAfterRun === false: return success without advancing
+            return {
+                status: 'SUCCESS',
+                contextUpdates: phaseOutput,
+            };
+        }
+        catch (err) {
+            // AC3: runner threw, or evaluateEntryGates/advancePhase threw unexpectedly
+            const message = err instanceof Error ? err.message : String(err);
+            return { status: 'FAILURE', failureReason: message };
+        }
+    };
+}
+//# sourceMappingURL=sdlc-phase-handler.js.map

package/dist/handlers/sdlc-phase-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdlc-phase-handler.js","sourceRoot":"","sources":["../../src/handlers/sdlc-phase-handler.ts"],"names":[],"mappings":"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"}

package/dist/handlers/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Type definitions for the SDLC handler module.
+ * Story 43-2.
+ *
+ * All types are defined locally — structurally compatible with monolith types
+ * but not compile-time coupled to the monolith or @substrate-ai/factory.
+ * See ADR-003: sdlc must NOT import from @substrate-ai/factory.
+ */
+/**
+ * Structured outcome returned by every SDLC node handler.
+ *
+ * Structurally compatible with Outcome from @substrate-ai/factory via
+ * TypeScript duck-typing — the CLI composition root can assign one to
+ * the other without any sdlc→factory import.
+ */
+export interface SdlcOutcome {
+    status: 'SUCCESS' | 'FAILURE' | 'PARTIAL_SUCCESS' | 'NEEDS_RETRY' | 'ESCALATE';
+    failureReason?: string;
+    contextUpdates?: Record<string, unknown>;
+    notes?: string;
+    /**
+     * Optional preferred edge label for the graph engine's edge selector.
+     * The graph engine uses this to match the DOT edge `label` attribute when
+     * choosing the next node after this handler returns.
+     * e.g., 'SHIP_IT' routes to exit, 'NEEDS_FIXES' routes back to dev_story.
+     */
+    preferredLabel?: string;
+}
+/**
+ * SDLC node handler type alias.
+ *
+ * Structurally compatible with NodeHandler from @substrate-ai/factory:
+ *   type NodeHandler = (node: GraphNode, context: IGraphContext, graph: Graph) => Promise<Outcome>
+ *
+ * TypeScript structural typing ensures the CLI composition root can assign
+ * SdlcNodeHandler to NodeHandler without any sdlc→factory import.
+ */
+export type SdlcNodeHandler = (node: {
+    id: string;
+    label: string;
+    prompt: string;
+}, context: {
+    getString(key: string, defaultValue?: string): string;
+}, graph: unknown) => Promise<SdlcOutcome>;
+/** Gate failure detail from a phase advance attempt. */
+export interface GateFailure {
+    gate: string;
+    error: string;
+}
+/** Result of attempting to advance the pipeline phase. */
+interface AdvancePhaseResult {
+    advanced: boolean;
+    phase: string;
+    gateFailures?: GateFailure[];
+}
+/**
+ * Result of evaluating entry gates before a phase dispatch.
+ * Story 43-13.
+ */
+export interface EntryGateResult {
+    passed: boolean;
+    failures?: GateFailure[];
+}
+/**
+ * Local minimal PhaseOrchestrator interface.
+ * Structurally compatible with the monolith PhaseOrchestrator.
+ * `advancePhase` handles post-runner exit gates; `evaluateEntryGates` handles
+ * pre-runner entry gates (added in story 43-13).
+ */
+export interface PhaseOrchestrator {
+    advancePhase(runId: string): Promise<AdvancePhaseResult>;
+    evaluateEntryGates(runId: string): Promise<EntryGateResult>;
+}
+/**
+ * Phase runner function type.
+ *
+ * Structurally compatible with the monolith phase runner signatures
+ * (runAnalysisPhase, runPlanningPhase, runSolutioningPhase) when called
+ * with the monolith's PhaseDeps and phase-specific params.
+ *
+ * `deps` is typed as `unknown` because PhaseDeps is defined in the monolith
+ * and this package has no need to inspect or modify it — it is passed through
+ * as-is from SdlcPhaseHandlerDeps.phaseDeps.
+ */
+export type PhaseRunnerFn = (deps: unknown, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * Map of phase name → runner function.
+ * Index signature allows additional phases to be registered without
+ * modifying the type (e.g., ux-design in a follow-on story).
+ */
+export interface PhaseRunners {
+    analysis: PhaseRunnerFn;
+    planning: PhaseRunnerFn;
+    solutioning: PhaseRunnerFn;
+    [key: string]: PhaseRunnerFn;
+}
+/**
+ * Dependency injection container for createSdlcPhaseHandler.
+ *
+ * Architecture note (ADR-003): phaseDeps is typed as `unknown` because
+ * PhaseDeps is defined in the monolith. It is passed through opaquely to the
+ * injected phase runner functions — this package has no need to inspect or
+ * modify it. The CLI composition root injects the concrete PhaseDeps instance
+ * at runtime.
+ *
+ * Phase runner functions are provided via `phases` to allow test injection of
+ * mocks without vi.mock — preferred per ADR-003 (no monolith compile-time
+ * coupling). At runtime the CLI composition root injects the real runners.
+ */
+export interface SdlcPhaseHandlerDeps {
+    /** Phase orchestrator for gate evaluation and phase advancement. */
+    orchestrator: PhaseOrchestrator;
+    /**
+     * Phase dependencies — passed through to runner functions.
+     * Typed as `unknown` to avoid compile-time coupling to monolith PhaseDeps.
+     */
+    phaseDeps: unknown;
+    /**
+     * Whether to call orchestrator.advancePhase() after each runner completes.
+     * Defaults to `true`. Pass `false` when managing phase advancement
+     * externally or in integration scenarios where only the runner is tested.
+     */
+    advanceAfterRun?: boolean;
+    /**
+     * Injectable phase runner functions — keyed by phase name (node.id).
+     * At runtime, the CLI composition root provides the real monolith runners.
+     * In tests, pass vi.fn() stubs directly (no vi.mock needed).
+     */
+    phases: PhaseRunners;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/handlers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,GAAG,aAAa,GAAG,UAAU,CAAA;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACnD,OAAO,EAAE;IAAE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EAClE,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,WAAW,CAAC,CAAA;AAMzB,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,0DAA0D;AAC1D,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,WAAW,EAAE,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACxD,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5D;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAErC;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAA;IACvB,QAAQ,EAAE,aAAa,CAAA;IACvB,WAAW,EAAE,aAAa,CAAA;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,YAAY,EAAE,iBAAiB,CAAA;IAC/B;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAA;CACrB"}