@hstm-labs/forge-reviewer 0.1.11

package/README.md

@@ -0,0 +1,43 @@
+# @hstm-labs/forge-reviewer
+
+Multi-pass AI code review stage for Forge — performs file-level, cross-file, spec-alignment, and synthesis review passes across all generated artifacts, producing structured findings with severity and remediation guidance.
+
+## Installation
+
+```bash
+npm install @hstm-labs/forge-reviewer
+```
+
+## Public API
+
+### Types
+
+- `CodeReviewReport` — complete review output with findings and summary
+- `CodeReviewFinding` — individual finding with file, line, severity, remediation
+- `ReviewDimension` — review category (correctness, security, performance, etc.)
+- `ReviewPassResult` — output from a single review pass
+- `ReviewFile` — file metadata for review input
+
+### Classes
+
+- `ReviewStage` — pipeline stage implementing `PipelineStage` interface (4 LLM calls)
+- `ReviewPassValidator` — validates individual review pass output
+- `ReviewSynthesisValidator` — validates final synthesis output
+
+### Functions
+
+- `collectReviewFiles(artifactsDir)` — gather generated files for review input
+
+## Usage
+
+```typescript
+import { ReviewStage } from '@hstm-labs/forge-reviewer';
+
+const stage = new ReviewStage();
+const result = await stage.execute(input);
+// result.data contains CodeReviewReport with findings from all 4 passes
+```
+
+## License
+
+[MIT](../../LICENSE)

package/dist/collect-review-files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * File collection helper for the AI code review stage.
+ *
+ * Extracts generated source code files from prior stage outputs
+ * into a flat list for review by the LLM.
+ */
+import type { ApiArtifact } from '@hstm-labs/forge-services-generator';
+import type { UiArtifact } from '@hstm-labs/forge-apps-generator';
+import type { SecurityArtifact } from '@hstm-labs/forge-security-generator';
+import type { InfraArtifact } from '@hstm-labs/forge-infra-generator';
+/** A file collected for review from a prior generation stage. */
+export interface ReviewFile {
+    /** File name or relative path. */
+    fileName: string;
+    /** File content (source code). */
+    content: string;
+    /** Which generation stage produced this file. */
+    stage: string;
+}
+/**
+ * Collect all generated source files from prior stage outputs for review.
+ *
+ * Source files are extracted from:
+ * - API: handlers, types
+ * - UI: pages, components, layouts, forms, navigation
+ * - Security: authModel, rbac, middleware, inputValidation, securityHeaders
+ * - Infra: containers, compose, ciPipeline
+ *
+ * @param api - API artifact (may be undefined)
+ * @param ui - UI artifact (may be undefined)
+ * @param security - Security artifact (may be undefined)
+ * @param infra - Infra artifact (may be undefined)
+ * @returns Array of review files
+ */
+export declare function collectReviewFiles(api: ApiArtifact | undefined, ui: UiArtifact | undefined, security: SecurityArtifact | undefined, infra: InfraArtifact | undefined): ReviewFile[];
+//# sourceMappingURL=collect-review-files.d.ts.map

package/dist/collect-review-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-review-files.d.ts","sourceRoot":"","sources":["../src/collect-review-files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAMtE,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,WAAW,GAAG,SAAS,EAC5B,EAAE,EAAE,UAAU,GAAG,SAAS,EAC1B,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,KAAK,EAAE,aAAa,GAAG,SAAS,GAC/B,UAAU,EAAE,CAyDd"}

package/dist/collect-review-files.js

@@ -0,0 +1,78 @@
+/**
+ * File collection helper for the AI code review stage.
+ *
+ * Extracts generated source code files from prior stage outputs
+ * into a flat list for review by the LLM.
+ */
+// ---------------------------------------------------------------------------
+// Collector
+// ---------------------------------------------------------------------------
+/**
+ * Collect all generated source files from prior stage outputs for review.
+ *
+ * Source files are extracted from:
+ * - API: handlers, types
+ * - UI: pages, components, layouts, forms, navigation
+ * - Security: authModel, rbac, middleware, inputValidation, securityHeaders
+ * - Infra: containers, compose, ciPipeline
+ *
+ * @param api - API artifact (may be undefined)
+ * @param ui - UI artifact (may be undefined)
+ * @param security - Security artifact (may be undefined)
+ * @param infra - Infra artifact (may be undefined)
+ * @returns Array of review files
+ */
+export function collectReviewFiles(api, ui, security, infra) {
+    const files = [];
+    // API: handlers + types
+    if (api !== undefined) {
+        for (const handler of api.handlers) {
+            files.push({ fileName: handler.fileName, content: handler.content, stage: 'services-generate' });
+        }
+        for (const typeDef of api.types) {
+            files.push({ fileName: typeDef.fileName, content: typeDef.content, stage: 'services-generate' });
+        }
+    }
+    // UI: pages, components, layouts, forms, navigation
+    if (ui !== undefined) {
+        for (const page of ui.pages) {
+            files.push({ fileName: page.fileName, content: page.content, stage: 'apps-generate' });
+        }
+        for (const component of ui.components) {
+            files.push({ fileName: component.fileName, content: component.content, stage: 'apps-generate' });
+        }
+        for (const layout of ui.layouts) {
+            files.push({ fileName: layout.fileName, content: layout.content, stage: 'apps-generate' });
+        }
+        for (const form of ui.forms) {
+            files.push({ fileName: form.fileName, content: form.content, stage: 'apps-generate' });
+        }
+        files.push({ fileName: ui.navigation.fileName, content: ui.navigation.content, stage: 'apps-generate' });
+    }
+    // Security: authModel, rbac, middleware, inputValidation, securityHeaders
+    if (security !== undefined) {
+        files.push({ fileName: security.authModel.fileName, content: security.authModel.content, stage: 'security-generate' });
+        files.push({ fileName: security.rbac.fileName, content: security.rbac.content, stage: 'security-generate' });
+        for (const mw of security.middleware) {
+            files.push({ fileName: mw.fileName, content: mw.content, stage: 'security-generate' });
+        }
+        for (const rule of security.inputValidation) {
+            files.push({ fileName: rule.fileName, content: rule.content, stage: 'security-generate' });
+        }
+        files.push({ fileName: security.securityHeaders.fileName, content: security.securityHeaders.content, stage: 'security-generate' });
+    }
+    // Infra: containers, compose, ciPipeline
+    if (infra !== undefined) {
+        for (const container of infra.containers) {
+            files.push({ fileName: container.fileName, content: container.content, stage: 'infra-generate' });
+        }
+        if (infra.compose !== undefined && infra.compose !== null) {
+            files.push({ fileName: infra.compose.fileName, content: infra.compose.content, stage: 'infra-generate' });
+        }
+        if (infra.ciPipeline !== undefined && infra.ciPipeline !== null) {
+            files.push({ fileName: infra.ciPipeline.fileName, content: infra.ciPipeline.content, stage: 'infra-generate' });
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=collect-review-files.js.map

package/dist/collect-review-files.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @hstm-labs/forge-reviewer — Multi-pass AI code review stage for Forge.
+ *
+ * Provides the {@link ReviewStage} pipeline stage, the
+ * {@link ReviewPassValidator} and {@link ReviewSynthesisValidator},
+ * and the {@link CodeReviewReport} type family describing review output.
+ *
+ * @packageDocumentation
+ */
+export type { CodeReviewReport, CodeReviewFinding, ReviewDimension, ReviewPassResult, } from './types.js';
+export { ReviewStage } from './review-stage.js';
+export { ReviewPassValidator, ReviewSynthesisValidator } from './validator.js';
+export { collectReviewFiles } from './collect-review-files.js';
+export type { ReviewFile } from './collect-review-files.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @hstm-labs/forge-reviewer — Multi-pass AI code review stage for Forge.
+ *
+ * Provides the {@link ReviewStage} pipeline stage, the
+ * {@link ReviewPassValidator} and {@link ReviewSynthesisValidator},
+ * and the {@link CodeReviewReport} type family describing review output.
+ *
+ * @packageDocumentation
+ */
+export { ReviewStage } from './review-stage.js';
+export { ReviewPassValidator, ReviewSynthesisValidator } from './validator.js';
+export { collectReviewFiles } from './collect-review-files.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/review-stage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-pass AI code review pipeline stage.
+ *
+ * Performs 4 LLM passes to analyze all generated artifacts:
+ * 1. **File-level pass** — individual file quality, security, best practices
+ * 2. **Cross-file pass** — import resolution, type consistency, contract alignment
+ * 3. **Spec-alignment pass** — requirements coverage, entity completeness
+ * 4. **Synthesis pass** — deduplication, severity validation, summary, pass/fail
+ *
+ * Each pass uses a shared system template but a distinct user prompt.
+ * The synthesis pass aggregates findings from passes 1-3.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import type { StageName } from '@hstm-labs/forge-common';
+import type { PipelineStage, PipelineStageInput, PipelineStageOutput, PipelineContext, AgentPromptContext } from '@hstm-labs/forge-core';
+/**
+ * Pipeline stage that performs a multi-pass AI code review.
+ *
+ * Produces a {@link CodeReviewReport} with findings from 4 LLM passes.
+ * The report is written as `review-report.json` and stored in
+ * `data.review` in the pipeline output.
+ *
+ * @example
+ * ```ts
+ * const stage = new ReviewStage();
+ * const output = await stage.execute(input, context);
+ * const report = output.data?.review as CodeReviewReport;
+ * ```
+ */
+export declare class ReviewStage implements PipelineStage {
+    readonly name: StageName;
+    readonly dependsOn: StageName[];
+    readonly requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `review-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input: PipelineStageInput, context: PipelineContext): AgentPromptContext;
+    /**
+     * Execute the multi-pass review stage.
+     *
+     * @param input - Input from all prior generation stages
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with review report artifact and CodeReviewReport in data
+     * @throws {ForgeError} FORGE-PIPE-003 if required dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     */
+    execute(input: PipelineStageInput, context: PipelineContext): Promise<PipelineStageOutput>;
+    /**
+     * Extract and validate all required dependency outputs.
+     *
+     * @param input - Pipeline stage input map
+     * @returns Structured dependency outputs
+     * @throws {ForgeError} if required dependencies are missing
+     */
+    private collectDependencies;
+    /**
+     * Parse findings array from LLM output JSON.
+     *
+     * @param content - Raw JSON string with `findings` key
+     * @returns Array of code review findings
+     */
+    private parseFindings;
+}
+//# sourceMappingURL=review-stage.d.ts.map

package/dist/review-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-stage.d.ts","sourceRoot":"","sources":["../src/review-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAEf,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AA6B/B;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,YAAW,aAAa;IAC/C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAY;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,CAO7B;IACF,QAAQ,CAAC,WAAW,QAAQ;IAE5B;;;;;;OAMG;IACH,eAAe,CACb,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,kBAAkB;IA+CrB;;;;;;;;OAQG;IACG,OAAO,CACX,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,mBAAmB,CAAC;IA2Q/B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA4G3B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAItB"}

package/dist/review-stage.js

@@ -0,0 +1,364 @@
+/**
+ * Multi-pass AI code review pipeline stage.
+ *
+ * Performs 4 LLM passes to analyze all generated artifacts:
+ * 1. **File-level pass** — individual file quality, security, best practices
+ * 2. **Cross-file pass** — import resolution, type consistency, contract alignment
+ * 3. **Spec-alignment pass** — requirements coverage, entity completeness
+ * 4. **Synthesis pass** — deduplication, severity validation, summary, pass/fail
+ *
+ * Each pass uses a shared system template but a distinct user prompt.
+ * The synthesis pass aggregates findings from passes 1-3.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import { join, dirname } from 'node:path';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { ForgeError, ErrorCodes, hashContent } from '@hstm-labs/forge-common';
+import { ApiStageExecutor } from '@hstm-labs/forge-core';
+import { loadProfile } from '@hstm-labs/forge-profiles';
+import { loadTemplate, renderTemplate } from '@hstm-labs/forge-templates';
+import { ReviewPassValidator, ReviewSynthesisValidator } from './validator.js';
+import { collectReviewFiles } from './collect-review-files.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const RETRY_POLICY = {
+    maxRetries: 3,
+    backoffMs: 1000,
+    includeErrorInRetry: true,
+};
+// ---------------------------------------------------------------------------
+// Stage
+// ---------------------------------------------------------------------------
+/**
+ * Pipeline stage that performs a multi-pass AI code review.
+ *
+ * Produces a {@link CodeReviewReport} with findings from 4 LLM passes.
+ * The report is written as `review-report.json` and stored in
+ * `data.review` in the pipeline output.
+ *
+ * @example
+ * ```ts
+ * const stage = new ReviewStage();
+ * const output = await stage.execute(input, context);
+ * const report = output.data?.review as CodeReviewReport;
+ * ```
+ */
+export class ReviewStage {
+    name = 'review';
+    dependsOn = [
+        'architect',
+        'services-generate',
+        'apps-generate',
+        'infra-generate',
+        'security-generate',
+        'seed-data',
+    ];
+    requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `review-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input, context) {
+        const parsedSpec = input['validate']?.data?.['parsedSpec'];
+        const architecture = input['architect']?.data?.['architecture'];
+        const api = input['services-generate']?.data?.['api'];
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'review', 'artifacts');
+        const agentTemplate = loadTemplate('review-agent', context.workspace.rootDir);
+        const rendered = renderTemplate(agentTemplate, {
+            spec: (parsedSpec ?? {}),
+            profile: profile,
+            architecture: (architecture ?? {}),
+            api: (api ?? {}),
+            stage: { outputDir },
+        });
+        return {
+            prompt: rendered.content,
+            outputSchema: {
+                format: 'json',
+                requiredFiles: ['review-report.json'],
+            },
+        };
+    }
+    /**
+     * Execute the multi-pass review stage.
+     *
+     * @param input - Input from all prior generation stages
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with review report artifact and CodeReviewReport in data
+     * @throws {ForgeError} FORGE-PIPE-003 if required dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     */
+    async execute(input, context) {
+        // 1. Collect all prior stage outputs
+        const { parsedSpec, architecture, api, ui, security, infra } = this.collectDependencies(input);
+        // 2. Require adapter
+        if (context.adapter === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Review stage requires an LLM adapter in API mode, but none was provided. ' +
+                'Configure an LLM provider in forge.config.json or use agent mode.');
+        }
+        // 3. Load profile
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        // 4. Compute output directory
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'review', 'artifacts');
+        // 5. Load shared system template
+        const systemTemplate = loadTemplate('review-system', context.workspace.rootDir);
+        const userTemplate = loadTemplate('review-user', context.workspace.rootDir);
+        const profileCtx = profile;
+        const systemPrompt = renderTemplate(systemTemplate, {
+            profile: profileCtx,
+        });
+        // 6. Collect review files
+        const reviewFiles = collectReviewFiles(api, ui, security, infra);
+        // 7. Shared template context for pass-specific templates
+        const specCtx = parsedSpec;
+        const archCtx = architecture;
+        const apiCtx = api;
+        const uiCtx = ui;
+        // -----------------------------------------------------------------------
+        // Pass 1: File-level review
+        // -----------------------------------------------------------------------
+        const filePassTemplate = loadTemplate('review-file-pass', context.workspace.rootDir);
+        const filePassRendered = renderTemplate(filePassTemplate, {
+            profile: profileCtx,
+            files: reviewFiles,
+        });
+        const filePassUserPrompt = renderTemplate(userTemplate, {
+            passPrompt: filePassRendered.content,
+        });
+        const passValidator = new ReviewPassValidator();
+        const filePassExecutor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator: passValidator,
+            retryPolicy: { ...RETRY_POLICY },
+        });
+        const filePassResult = await filePassExecutor.execute({
+            prompt: filePassUserPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'review',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        const filePassFindings = this.parseFindings(filePassResult.artifacts[0]?.content ?? '{"findings":[]}');
+        // -----------------------------------------------------------------------
+        // Pass 2: Cross-file review
+        // -----------------------------------------------------------------------
+        const crossFileTemplate = loadTemplate('review-crossfile-pass', context.workspace.rootDir);
+        const crossFileRendered = renderTemplate(crossFileTemplate, {
+            api: apiCtx,
+            ui: uiCtx,
+            architecture: archCtx,
+        });
+        const crossFileUserPrompt = renderTemplate(userTemplate, {
+            passPrompt: crossFileRendered.content,
+        });
+        const crossFileExecutor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator: passValidator,
+            retryPolicy: { ...RETRY_POLICY },
+        });
+        const crossFileResult = await crossFileExecutor.execute({
+            prompt: crossFileUserPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'review',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        const crossFileFindings = this.parseFindings(crossFileResult.artifacts[0]?.content ?? '{"findings":[]}');
+        // -----------------------------------------------------------------------
+        // Pass 3: Spec-alignment review
+        // -----------------------------------------------------------------------
+        const specAlignTemplate = loadTemplate('review-specalign-pass', context.workspace.rootDir);
+        const specAlignRendered = renderTemplate(specAlignTemplate, {
+            spec: specCtx,
+            architecture: archCtx,
+            api: apiCtx,
+            ui: uiCtx,
+        });
+        const specAlignUserPrompt = renderTemplate(userTemplate, {
+            passPrompt: specAlignRendered.content,
+        });
+        const specAlignExecutor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator: passValidator,
+            retryPolicy: { ...RETRY_POLICY },
+        });
+        const specAlignResult = await specAlignExecutor.execute({
+            prompt: specAlignUserPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'review',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        const specAlignFindings = this.parseFindings(specAlignResult.artifacts[0]?.content ?? '{"findings":[]}');
+        // -----------------------------------------------------------------------
+        // Aggregate and renumber findings from passes 1-3
+        // -----------------------------------------------------------------------
+        const allPreviousFindings = [
+            ...filePassFindings,
+            ...crossFileFindings,
+            ...specAlignFindings,
+        ];
+        const renumberedFindings = allPreviousFindings.map((f, idx) => ({
+            ...f,
+            id: `REVIEW-${String(idx + 1).padStart(3, '0')}`,
+        }));
+        // -----------------------------------------------------------------------
+        // Pass 4: Synthesis
+        // -----------------------------------------------------------------------
+        const synthesisTemplate = loadTemplate('review-synthesis-pass', context.workspace.rootDir);
+        const synthesisRendered = renderTemplate(synthesisTemplate, {
+            previousFindings: renumberedFindings,
+        });
+        const synthesisUserPrompt = renderTemplate(userTemplate, {
+            passPrompt: synthesisRendered.content,
+        });
+        const synthesisValidator = new ReviewSynthesisValidator();
+        const synthesisExecutor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator: synthesisValidator,
+            retryPolicy: { ...RETRY_POLICY },
+        });
+        const synthesisResult = await synthesisExecutor.execute({
+            prompt: synthesisUserPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'review',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        const synthesisData = JSON.parse(synthesisResult.artifacts[0]?.content ?? '{"findings":[],"summary":"","passOrFail":"pass"}');
+        // -----------------------------------------------------------------------
+        // Build CodeReviewReport
+        // -----------------------------------------------------------------------
+        const uniqueFiles = new Set(reviewFiles.map((f) => f.fileName));
+        const report = {
+            runId: context.runId,
+            reviewedAt: new Date().toISOString(),
+            totalFiles: uniqueFiles.size,
+            totalFindings: synthesisData.findings.length,
+            findingsBySeverity: {
+                critical: synthesisData.findings.filter((f) => f.severity === 'critical').length,
+                warning: synthesisData.findings.filter((f) => f.severity === 'warning').length,
+                suggestion: synthesisData.findings.filter((f) => f.severity === 'suggestion').length,
+            },
+            findings: synthesisData.findings,
+            summary: synthesisData.summary,
+            passOrFail: synthesisData.passOrFail,
+        };
+        // -----------------------------------------------------------------------
+        // Write report
+        // -----------------------------------------------------------------------
+        const reportJson = JSON.stringify(report, null, 2);
+        const reportPath = 'review-report.json';
+        const fullPath = join(outputDir, reportPath);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        writeFileSync(fullPath, reportJson, 'utf-8');
+        const artifacts = [
+            {
+                filePath: reportPath,
+                content: reportJson,
+                contentHash: hashContent(reportJson),
+                sizeBytes: Buffer.byteLength(reportJson, 'utf-8'),
+            },
+        ];
+        return {
+            artifacts,
+            data: {
+                review: report,
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Extract and validate all required dependency outputs.
+     *
+     * @param input - Pipeline stage input map
+     * @returns Structured dependency outputs
+     * @throws {ForgeError} if required dependencies are missing
+     */
+    collectDependencies(input) {
+        // Validate stage
+        const validateOutput = input['validate'];
+        if (validateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'validate' stage output, but it was not found. " +
+                'Ensure the validate stage runs before the review stage.');
+        }
+        const parsedSpec = validateOutput.data?.['parsedSpec'];
+        if (parsedSpec === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Validate stage did not produce a parsed specification in its output data.');
+        }
+        // Architect stage
+        const architectOutput = input['architect'];
+        if (architectOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'architect' stage output, but it was not found.");
+        }
+        const architecture = architectOutput.data?.['architecture'];
+        if (architecture === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Architect stage did not produce an architecture in its output data.');
+        }
+        // API generate stage
+        const apiOutput = input['services-generate'];
+        if (apiOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'services-generate' stage output, but it was not found.");
+        }
+        const api = apiOutput.data?.['api'];
+        if (api === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'API generate stage did not produce an API artifact in its output data.');
+        }
+        // UI generate stage
+        const uiOutput = input['apps-generate'];
+        if (uiOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'apps-generate' stage output, but it was not found.");
+        }
+        const ui = uiOutput.data?.['ui'];
+        if (ui === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'UI generate stage did not produce a UI artifact in its output data.');
+        }
+        // Security generate stage
+        const securityOutput = input['security-generate'];
+        if (securityOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'security-generate' stage output, but it was not found.");
+        }
+        const security = securityOutput.data?.['security'];
+        if (security === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Security generate stage did not produce a security artifact in its output data.');
+        }
+        // Infra generate stage
+        const infraOutput = input['infra-generate'];
+        if (infraOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Review stage requires 'infra-generate' stage output, but it was not found.");
+        }
+        const infra = infraOutput.data?.['infra'];
+        if (infra === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Infra generate stage did not produce an infra artifact in its output data.');
+        }
+        return { parsedSpec, architecture, api, ui, security, infra };
+    }
+    /**
+     * Parse findings array from LLM output JSON.
+     *
+     * @param content - Raw JSON string with `findings` key
+     * @returns Array of code review findings
+     */
+    parseFindings(content) {
+        const parsed = JSON.parse(content);
+        return parsed.findings;
+    }
+}
+//# sourceMappingURL=review-stage.js.map

package/dist/review-stage.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Code review artifact type definitions for the Forge review stage.
+ *
+ * Defines the multi-pass review output schema including individual
+ * findings, the aggregated report, and per-pass result structure.
+ */
+/** Review dimensions checked by the AI code review stage. */
+export type ReviewDimension = 'code-quality' | 'security' | 'performance' | 'best-practices' | 'consistency' | 'architecture' | 'spec-adherence';
+/** A single code review finding. */
+export interface CodeReviewFinding {
+    /** Finding ID: REVIEW-{NNN}. */
+    id: string;
+    /** Severity level. */
+    severity: 'critical' | 'warning' | 'suggestion';
+    /** Review dimension. */
+    dimension: ReviewDimension;
+    /** Relative path to reviewed file. */
+    file: string;
+    /** Line number if applicable. */
+    line?: number | undefined;
+    /** One-line summary. */
+    title: string;
+    /** Detailed explanation. */
+    description: string;
+    /** Code snippet with suggested correction. */
+    suggestedFix?: string | undefined;
+    /** Requirement ID if spec-related. */
+    specReference?: string | undefined;
+}
+/** Complete code review report produced by the review stage. */
+export interface CodeReviewReport {
+    /** Run ID. */
+    runId: string;
+    /** ISO timestamp of review. */
+    reviewedAt: string;
+    /** Total files reviewed. */
+    totalFiles: number;
+    /** Total findings. */
+    totalFindings: number;
+    /** Findings broken down by severity. */
+    findingsBySeverity: {
+        critical: number;
+        warning: number;
+        suggestion: number;
+    };
+    /** All findings. */
+    findings: CodeReviewFinding[];
+    /** LLM-generated natural language summary. */
+    summary: string;
+    /** Pass if no critical findings; fail if any critical findings. */
+    passOrFail: 'pass' | 'fail';
+}
+/** Raw findings from a single review pass (what the LLM returns). */
+export interface ReviewPassResult {
+    /** Pass name. */
+    pass: 'file-level' | 'cross-file' | 'spec-alignment' | 'synthesis';
+    /** Findings from this pass. */
+    findings: CodeReviewFinding[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAMrB,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;IAChD,wBAAwB;IACxB,SAAS,EAAE,eAAe,CAAC;IAC3B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAMD,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,kBAAkB,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,oBAAoB;IACpB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAMD,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,gBAAgB,GAAG,WAAW,CAAC;IACnE,+BAA+B;IAC/B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Code review artifact type definitions for the Forge review stage.
+ *
+ * Defines the multi-pass review output schema including individual
+ * findings, the aggregated report, and per-pass result structure.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/validator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Code review output validators for the Forge review stage.
+ *
+ * Two validators are provided:
+ * - {@link ReviewPassValidator} — validates individual pass output (file-level, cross-file, spec-alignment)
+ * - {@link ReviewSynthesisValidator} — validates the synthesis pass output (aggregated report)
+ */
+import type { OutputValidator, OutputSchema, ValidationResult } from '@hstm-labs/forge-core';
+/**
+ * Validates individual review pass output from the LLM.
+ *
+ * Checks:
+ * 1. JSON parse validation
+ * 2. `findings` key is an array
+ * 3. Each finding has required fields: id, severity, dimension, file, title, description
+ * 4. `severity` is one of: critical, warning, suggestion
+ * 5. `dimension` is a valid ReviewDimension
+ * 6. `id` matches REVIEW-{NNN} pattern
+ *
+ * @example
+ * ```ts
+ * const validator = new ReviewPassValidator();
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export declare class ReviewPassValidator implements OutputValidator {
+    /**
+     * Validate a single review pass output.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    validate(output: string, _schema: OutputSchema): ValidationResult;
+}
+/**
+ * Validates the synthesis pass output from the LLM.
+ *
+ * Checks:
+ * 1. JSON parse validation
+ * 2. `findings` array, `summary` string, `passOrFail` string
+ * 3. `passOrFail` is 'pass' or 'fail'
+ * 4. Consistency: if any finding has severity 'critical', passOrFail must be 'fail'
+ *
+ * @example
+ * ```ts
+ * const validator = new ReviewSynthesisValidator();
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export declare class ReviewSynthesisValidator implements OutputValidator {
+    /**
+     * Validate the synthesis pass output.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    validate(output: string, _schema: OutputSchema): ValidationResult;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AA0B/B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD;;;;;;OAMG;IAEH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,gBAAgB;CA0FlE;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAC9D;;;;;;OAMG;IAEH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,gBAAgB;CAuElE"}

package/dist/validator.js

@@ -0,0 +1,221 @@
+/**
+ * Code review output validators for the Forge review stage.
+ *
+ * Two validators are provided:
+ * - {@link ReviewPassValidator} — validates individual pass output (file-level, cross-file, spec-alignment)
+ * - {@link ReviewSynthesisValidator} — validates the synthesis pass output (aggregated report)
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const VALID_SEVERITIES = new Set(['critical', 'warning', 'suggestion']);
+const VALID_DIMENSIONS = new Set([
+    'code-quality',
+    'security',
+    'performance',
+    'best-practices',
+    'consistency',
+    'architecture',
+    'spec-adherence',
+]);
+const FINDING_ID_PATTERN = /^REVIEW-\d{3,}$/;
+// ---------------------------------------------------------------------------
+// ReviewPassValidator
+// ---------------------------------------------------------------------------
+/**
+ * Validates individual review pass output from the LLM.
+ *
+ * Checks:
+ * 1. JSON parse validation
+ * 2. `findings` key is an array
+ * 3. Each finding has required fields: id, severity, dimension, file, title, description
+ * 4. `severity` is one of: critical, warning, suggestion
+ * 5. `dimension` is a valid ReviewDimension
+ * 6. `id` matches REVIEW-{NNN} pattern
+ *
+ * @example
+ * ```ts
+ * const validator = new ReviewPassValidator();
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export class ReviewPassValidator {
+    /**
+     * Validate a single review pass output.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    validate(output, _schema) {
+        const errors = [];
+        // 1. Parse as JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(output);
+        }
+        catch {
+            errors.push({
+                message: 'Review pass output is not valid JSON. Ensure the LLM produces only raw JSON without markdown fences or explanatory text.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            errors.push({
+                message: 'Review pass output must be a JSON object, not an array or primitive.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        const obj = parsed;
+        // 2. Verify findings key is an array
+        const findings = obj['findings'];
+        if (!Array.isArray(findings)) {
+            errors.push({
+                message: "Key 'findings' must be an array of finding objects.",
+                path: 'findings',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        // 3-6. Validate each finding
+        for (let i = 0; i < findings.length; i++) {
+            const f = findings[i];
+            if (f === undefined || typeof f !== 'object' || f === null) {
+                errors.push({
+                    message: `findings[${String(i)}] is not a valid object.`,
+                    path: `findings[${String(i)}]`,
+                    severity: 'error',
+                });
+                continue;
+            }
+            // 3. Required fields
+            for (const field of ['id', 'severity', 'dimension', 'file', 'title', 'description']) {
+                if (typeof f[field] !== 'string' || f[field].length === 0) {
+                    errors.push({
+                        message: `findings[${String(i)}] is missing required field '${field}'.`,
+                        path: `findings[${String(i)}].${field}`,
+                        severity: 'error',
+                    });
+                }
+            }
+            // 4. Valid severity
+            if (typeof f['severity'] === 'string' && !VALID_SEVERITIES.has(f['severity'])) {
+                errors.push({
+                    message: `findings[${String(i)}].severity '${f['severity']}' is invalid. Must be one of: critical, warning, suggestion.`,
+                    path: `findings[${String(i)}].severity`,
+                    severity: 'error',
+                });
+            }
+            // 5. Valid dimension
+            if (typeof f['dimension'] === 'string' && !VALID_DIMENSIONS.has(f['dimension'])) {
+                errors.push({
+                    message: `findings[${String(i)}].dimension '${f['dimension']}' is invalid. Must be a valid ReviewDimension.`,
+                    path: `findings[${String(i)}].dimension`,
+                    severity: 'error',
+                });
+            }
+            // 6. ID pattern
+            if (typeof f['id'] === 'string' && !FINDING_ID_PATTERN.test(f['id'])) {
+                errors.push({
+                    message: `findings[${String(i)}].id '${f['id']}' does not match REVIEW-{NNN} pattern.`,
+                    path: `findings[${String(i)}].id`,
+                    severity: 'error',
+                });
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}
+// ---------------------------------------------------------------------------
+// ReviewSynthesisValidator
+// ---------------------------------------------------------------------------
+/**
+ * Validates the synthesis pass output from the LLM.
+ *
+ * Checks:
+ * 1. JSON parse validation
+ * 2. `findings` array, `summary` string, `passOrFail` string
+ * 3. `passOrFail` is 'pass' or 'fail'
+ * 4. Consistency: if any finding has severity 'critical', passOrFail must be 'fail'
+ *
+ * @example
+ * ```ts
+ * const validator = new ReviewSynthesisValidator();
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export class ReviewSynthesisValidator {
+    /**
+     * Validate the synthesis pass output.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    validate(output, _schema) {
+        const errors = [];
+        // 1. Parse as JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(output);
+        }
+        catch {
+            errors.push({
+                message: 'Synthesis pass output is not valid JSON. Ensure the LLM produces only raw JSON without markdown fences or explanatory text.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            errors.push({
+                message: 'Synthesis pass output must be a JSON object, not an array or primitive.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        const obj = parsed;
+        // 2. Verify findings, summary, passOrFail
+        if (!Array.isArray(obj['findings'])) {
+            errors.push({
+                message: "Key 'findings' must be an array of finding objects.",
+                path: 'findings',
+                severity: 'error',
+            });
+        }
+        if (typeof obj['summary'] !== 'string' || obj['summary'].length === 0) {
+            errors.push({
+                message: "Key 'summary' must be a non-empty string.",
+                path: 'summary',
+                severity: 'error',
+            });
+        }
+        // 3. passOrFail is 'pass' or 'fail'
+        if (obj['passOrFail'] !== 'pass' && obj['passOrFail'] !== 'fail') {
+            errors.push({
+                message: "Key 'passOrFail' must be 'pass' or 'fail'.",
+                path: 'passOrFail',
+                severity: 'error',
+            });
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        // 4. Consistency check: critical findings → passOrFail must be 'fail'
+        const findings = obj['findings'];
+        const hasCritical = findings.some((f) => f['severity'] === 'critical');
+        if (hasCritical && obj['passOrFail'] === 'pass') {
+            errors.push({
+                message: "Consistency error: findings contain critical severity issues but passOrFail is 'pass'. " +
+                    "Any critical finding must result in passOrFail='fail'.",
+                path: 'passOrFail',
+                severity: 'error',
+            });
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hstm-labs/forge-reviewer",
+  "version": "0.1.11",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hstm-labs/forge-common": "0.1.11",
+    "@hstm-labs/forge-core": "0.1.11",
+    "@hstm-labs/forge-architect": "0.1.11",
+    "@hstm-labs/forge-services-generator": "0.1.11",
+    "@hstm-labs/forge-apps-generator": "0.1.11",
+    "@hstm-labs/forge-infra-generator": "0.1.11",
+    "@hstm-labs/forge-security-generator": "0.1.11",
+    "@hstm-labs/forge-seed-data": "0.1.11",
+    "@hstm-labs/forge-spec-parser": "0.1.11",
+    "@hstm-labs/forge-profiles": "0.1.11",
+    "@hstm-labs/forge-templates": "0.1.11"
+  }
+}