@hyperdrive.bot/bmad-workflow 1.0.18 → 1.0.19

package/dist/services/review/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Review Types
+ *
+ * Core type definitions for the automated code review system.
+ * Scanners return raw output; classification into severity levels
+ * is handled separately by SeverityClassifier (Story 1.2).
+ *
+ * Severity model maps to BMAD governance:
+ *   CRITICAL = NON-NEGOTIABLE (blocks pipeline)
+ *   HIGH     = MUST (blocks pipeline)
+ *   MEDIUM   = SHOULD (documented as tech debt)
+ *   LOW      = MAY (noted only)
+ */
+/**
+ * Issue severity levels aligned with BMAD governance tiers
+ */
+export declare enum Severity {
+    CRITICAL = "CRITICAL",
+    HIGH = "HIGH",
+    LOW = "LOW",
+    MEDIUM = "MEDIUM"
+}
+/**
+ * Review verdict — PASS allows pipeline to continue, FAIL blocks it
+ */
+export type ReviewVerdict = 'FAIL' | 'PASS';
+/**
+ * Context provided to scanners describing what to review
+ */
+export interface ReviewContext {
+    /** Base branch to diff against (e.g., "main", "develop") */
+    baseBranch: string;
+    /** List of changed file paths (relative to projectRoot) */
+    changedFiles: string[];
+    /** Absolute path to the project root directory */
+    projectRoot: string;
+    /** List of reference file paths for context (e.g., architecture docs) */
+    referenceFiles: string[];
+    /** Absolute path to the story markdown file */
+    storyFile: string;
+    /** Story identifier (e.g., "PROJ-story-1.001") */
+    storyId: string;
+}
+/**
+ * Raw output from a scanner before classification
+ */
+export interface RawReviewOutput {
+    /** Raw scanner output (lint text, AI response, etc.) */
+    raw: string;
+    /** Identifier of the scanner that produced this output (e.g., "eslint", "claude-ai", "coderabbit") */
+    source: string;
+}
+/**
+ * A single classified issue with severity and location
+ */
+export interface ClassifiedIssue {
+    /** File path where the issue was found */
+    file: string;
+    /** Suggested fix (optional) */
+    fix?: string;
+    /** Description of the issue */
+    issue: string;
+    /** Line number where the issue occurs */
+    line: number;
+    /** Severity level of the issue */
+    severity: Severity;
+}
+/**
+ * Final review result after classification and optional self-heal iterations
+ */
+export interface ReviewResult {
+    /** All classified issues found during review */
+    issues: ClassifiedIssue[];
+    /** Number of self-heal iterations performed (0 if no retries) */
+    iterations: number;
+    /** Optional summary message */
+    message?: string;
+    /** Overall verdict — PASS or FAIL */
+    verdict: ReviewVerdict;
+}
+/**
+ * Scanner interface — all scanner implementations (lint, AI, CodeRabbit) must implement this.
+ * Mirrors the AIProviderRunner pattern: single async method with typed input/output.
+ */
+export interface ReviewScanner {
+    /**
+     * Scan the given context and produce raw review output
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from the scanner
+     */
+    scan(context: ReviewContext): Promise<RawReviewOutput>;
+}

package/dist/services/review/types.js

@@ -0,0 +1,23 @@
+/**
+ * Review Types
+ *
+ * Core type definitions for the automated code review system.
+ * Scanners return raw output; classification into severity levels
+ * is handled separately by SeverityClassifier (Story 1.2).
+ *
+ * Severity model maps to BMAD governance:
+ *   CRITICAL = NON-NEGOTIABLE (blocks pipeline)
+ *   HIGH     = MUST (blocks pipeline)
+ *   MEDIUM   = SHOULD (documented as tech debt)
+ *   LOW      = MAY (noted only)
+ */
+/**
+ * Issue severity levels aligned with BMAD governance tiers
+ */
+export var Severity;
+(function (Severity) {
+    Severity["CRITICAL"] = "CRITICAL";
+    Severity["HIGH"] = "HIGH";
+    Severity["LOW"] = "LOW";
+    Severity["MEDIUM"] = "MEDIUM";
+})(Severity || (Severity = {}));

package/dist/services/validation/config-validator.d.ts

@@ -8,6 +8,53 @@
 import type pino from 'pino';
 import { z } from 'zod';
 import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * Zod schema for review configuration section
+ *
+ * Defines scanners, severity thresholds, self-heal limits, and path rules
+ * for automated code review in the BMAD workflow pipeline.
+ */
+export declare const reviewConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    pathRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        focus: z.ZodString;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>;
+    scanners: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        ai: "ai";
+        coderabbit: "coderabbit";
+        lint: "lint";
+    }>>>;
+    selfHeal: z.ZodDefault<z.ZodObject<{
+        fixAgent: z.ZodDefault<z.ZodString>;
+        fixTimeout: z.ZodDefault<z.ZodNumber>;
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    severity: z.ZodDefault<z.ZodObject<{
+        blockOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+        documentOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+        ignoreOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Inferred TypeScript type from review config Zod schema
+ */
+export type ReviewConfig = z.infer<typeof reviewConfigSchema>;
 /**
  * Zod schema for core configuration
  *
@@ -22,6 +69,43 @@ declare const configSchema: z.ZodObject<{
     qa: z.ZodOptional<z.ZodObject<{
         qaLocation: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    review: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        pathRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            focus: z.ZodString;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        scanners: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            ai: "ai";
+            coderabbit: "coderabbit";
+            lint: "lint";
+        }>>>;
+        selfHeal: z.ZodDefault<z.ZodObject<{
+            fixAgent: z.ZodDefault<z.ZodString>;
+            fixTimeout: z.ZodDefault<z.ZodNumber>;
+            maxIterations: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        severity: z.ZodDefault<z.ZodObject<{
+            blockOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+            documentOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+            ignoreOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * Inferred TypeScript type from Zod schema

package/dist/services/validation/config-validator.js

@@ -7,6 +7,77 @@
  */
 import { z } from 'zod';
 import { ValidationError } from '../../utils/errors.js';
+/**
+ * Valid scanner identifiers for automated code review
+ */
+const VALID_SCANNERS = ['ai', 'lint', 'coderabbit'];
+/**
+ * Valid severity levels
+ */
+const VALID_SEVERITIES = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
+/**
+ * Zod schema for review.severity configuration
+ */
+const severityArraySchema = z.array(z.enum(VALID_SEVERITIES, {
+    message: `Invalid severity level. Valid values: ${VALID_SEVERITIES.join(', ')}`,
+}));
+/**
+ * Zod schema for review.pathRules entries
+ */
+const pathRuleSchema = z.object({
+    focus: z.string().min(1, { message: 'Path rule focus description is required' }),
+    pattern: z.string().min(1, { message: 'Path rule pattern is required' }),
+});
+/**
+ * Zod schema for review configuration section
+ *
+ * Defines scanners, severity thresholds, self-heal limits, and path rules
+ * for automated code review in the BMAD workflow pipeline.
+ */
+export const reviewConfigSchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    pathRules: z.array(pathRuleSchema).optional(),
+    scanners: z
+        .array(z.enum(VALID_SCANNERS, {
+        message: `Unknown scanner name. Valid values: ${VALID_SCANNERS.join(', ')}`,
+    }))
+        .default(['ai', 'lint']),
+    selfHeal: z
+        .object({
+        fixAgent: z.string().default('dev'),
+        fixTimeout: z.number().int().positive({ message: 'selfHeal.fixTimeout must be a positive integer' }).default(300_000),
+        maxIterations: z
+            .number()
+            .int()
+            .positive({ message: 'selfHeal.maxIterations must be a positive integer' })
+            .default(3),
+    })
+        .default(() => ({ fixAgent: 'dev', fixTimeout: 300_000, maxIterations: 3 })),
+    severity: z
+        .object({
+        blockOn: severityArraySchema.default(['CRITICAL', 'HIGH']),
+        documentOn: severityArraySchema.default(['MEDIUM']),
+        ignoreOn: severityArraySchema.default(['LOW']),
+    })
+        .default(() => ({
+        blockOn: ['CRITICAL', 'HIGH'],
+        documentOn: ['MEDIUM'],
+        ignoreOn: ['LOW'],
+    })),
+})
+    .superRefine((data, ctx) => {
+    // Validate that blockOn and ignoreOn do not overlap
+    const blockSet = new Set(data.severity.blockOn);
+    const overlapping = data.severity.ignoreOn.filter((s) => blockSet.has(s));
+    if (overlapping.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `severity.blockOn and severity.ignoreOn must not overlap. Overlapping: ${overlapping.join(', ')}`,
+            path: ['severity'],
+        });
+    }
+});
 /**
  * Zod schema for core configuration
  *
@@ -25,6 +96,7 @@ const configSchema = z.object({
         qaLocation: z.string().optional(),
     })
         .optional(),
+    review: reviewConfigSchema.optional(),
 });
 /**
  * ConfigValidator service validates configuration files against schemas
@@ -105,11 +177,17 @@ export class ConfigValidator {
             devStoryLocation: 'docs/stories',
             'prd.prdFile': 'docs/prd.md',
             'qa.qaLocation': 'docs/qa',
+            'review.scanners': '[ai, lint]',
+            'review.severity.blockOn': '[CRITICAL, HIGH]',
+            'review.selfHeal.maxIterations': '3',
         };
         const fieldDisplayNames = {
             devStoryLocation: 'Story directory path (devStoryLocation)',
             'prd.prdFile': 'PRD file path (prd.prdFile)',
             'qa.qaLocation': 'QA location path (qa.qaLocation)',
+            'review.scanners': 'Review scanners (review.scanners)',
+            'review.severity.blockOn': 'Review severity blockOn (review.severity.blockOn)',
+            'review.selfHeal.maxIterations': 'Self-heal max iterations (review.selfHeal.maxIterations)',
         };
         const example = examples[fieldName] || 'path/to/directory';
         const displayName = fieldDisplayNames[fieldName] || fieldName;

package/dist/utils/credential-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Credential utility functions
+ *
+ * Shared helpers for credential display masking.
+ */
+/**
+ * Mask a credential value for display.
+ * Shows first 3 chars + '***...***' + last 3 chars.
+ * For values shorter than 8 chars, mask entirely as '***'.
+ *
+ * @param value - The raw credential value
+ * @returns Masked string safe for display
+ */
+export declare function maskValue(value: string): string;

package/dist/utils/credential-utils.js

@@ -0,0 +1,19 @@
+/**
+ * Credential utility functions
+ *
+ * Shared helpers for credential display masking.
+ */
+/**
+ * Mask a credential value for display.
+ * Shows first 3 chars + '***...***' + last 3 chars.
+ * For values shorter than 8 chars, mask entirely as '***'.
+ *
+ * @param value - The raw credential value
+ * @returns Masked string safe for display
+ */
+export function maskValue(value) {
+    if (value.length < 8) {
+        return '***';
+    }
+    return `${value.slice(0, 3)}***...***${value.slice(-3)}`;
+}

package/dist/utils/duration.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Duration Parsing Utility
+ *
+ * Parses human-readable duration strings (e.g., "30s", "5m", "1h", "90m")
+ * into milliseconds. Also accepts raw millisecond numbers for backward
+ * compatibility with existing --timeout flag usage.
+ *
+ * @example
+ * ```typescript
+ * parseDuration('30s')      // 30_000
+ * parseDuration('5m')       // 300_000
+ * parseDuration('45m')      // 2_700_000
+ * parseDuration('1h')       // 3_600_000
+ * parseDuration('1.5h')     // 5_400_000
+ * parseDuration('2700000')  // 2_700_000 (raw ms, backward compat)
+ * parseDuration(2700000)    // 2_700_000 (numeric passthrough)
+ * ```
+ */
+/**
+ * Parse a duration string or number into milliseconds.
+ *
+ * Accepted formats:
+ * - `"30s"` — seconds
+ * - `"5m"` — minutes
+ * - `"1h"` — hours
+ * - `"1.5h"` — fractional units
+ * - `"2700000"` — raw milliseconds (string)
+ * - `2700000` — raw milliseconds (number)
+ *
+ * @param input - Duration string or number
+ * @returns Duration in milliseconds
+ * @throws Error if the input format is invalid or value is non-positive
+ */
+export declare function parseDuration(input: number | string): number;
+/**
+ * Format a millisecond duration into a human-readable string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted string (e.g., "45m", "1.5h", "30s")
+ */
+export declare function formatDuration(ms: number): string;

package/dist/utils/duration.js

@@ -0,0 +1,89 @@
+/**
+ * Duration Parsing Utility
+ *
+ * Parses human-readable duration strings (e.g., "30s", "5m", "1h", "90m")
+ * into milliseconds. Also accepts raw millisecond numbers for backward
+ * compatibility with existing --timeout flag usage.
+ *
+ * @example
+ * ```typescript
+ * parseDuration('30s')      // 30_000
+ * parseDuration('5m')       // 300_000
+ * parseDuration('45m')      // 2_700_000
+ * parseDuration('1h')       // 3_600_000
+ * parseDuration('1.5h')     // 5_400_000
+ * parseDuration('2700000')  // 2_700_000 (raw ms, backward compat)
+ * parseDuration(2700000)    // 2_700_000 (numeric passthrough)
+ * ```
+ */
+/** Duration unit multipliers in milliseconds */
+const UNIT_MS = {
+    h: 3_600_000,
+    m: 60_000,
+    s: 1_000,
+};
+/**
+ * Parse a duration string or number into milliseconds.
+ *
+ * Accepted formats:
+ * - `"30s"` — seconds
+ * - `"5m"` — minutes
+ * - `"1h"` — hours
+ * - `"1.5h"` — fractional units
+ * - `"2700000"` — raw milliseconds (string)
+ * - `2700000` — raw milliseconds (number)
+ *
+ * @param input - Duration string or number
+ * @returns Duration in milliseconds
+ * @throws Error if the input format is invalid or value is non-positive
+ */
+export function parseDuration(input) {
+    // Numeric passthrough
+    if (typeof input === 'number') {
+        if (input <= 0 || !Number.isFinite(input)) {
+            throw new Error(`Invalid timeout value: ${input}. Must be a positive number.`);
+        }
+        return Math.round(input);
+    }
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Timeout value cannot be empty.');
+    }
+    // Try matching duration pattern: number + unit suffix
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*(s|m|h)$/i);
+    if (match) {
+        const value = Number.parseFloat(match[1]);
+        const unit = match[2].toLowerCase();
+        const multiplier = UNIT_MS[unit];
+        const ms = Math.round(value * multiplier);
+        if (ms <= 0) {
+            throw new Error(`Invalid timeout value: ${trimmed}. Must result in a positive duration.`);
+        }
+        return ms;
+    }
+    // Try raw numeric string (milliseconds)
+    const numeric = Number(trimmed);
+    if (!Number.isNaN(numeric) && Number.isFinite(numeric) && numeric > 0) {
+        return Math.round(numeric);
+    }
+    throw new Error(`Invalid timeout format: "${trimmed}". ` +
+        `Expected a duration like "30s", "5m", "1h", "90m", or raw milliseconds like "2700000".`);
+}
+/**
+ * Format a millisecond duration into a human-readable string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted string (e.g., "45m", "1.5h", "30s")
+ */
+export function formatDuration(ms) {
+    if (ms >= 3_600_000) {
+        const hours = ms / 3_600_000;
+        return Number.isInteger(hours) ? `${hours}h` : `${hours.toFixed(1)}h`;
+    }
+    if (ms >= 60_000) {
+        const minutes = ms / 60_000;
+        return Number.isInteger(minutes) ? `${minutes}m` : `${minutes.toFixed(1)}m`;
+    }
+    const seconds = ms / 1_000;
+    return Number.isInteger(seconds) ? `${seconds}s` : `${seconds.toFixed(1)}s`;
+}

package/dist/utils/shared-flags.d.ts

@@ -27,6 +27,7 @@ export declare const agentFlags: {
     provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     task: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    'review-timeout': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
     'max-retries': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     'retry-backoff': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
 };

package/dist/utils/shared-flags.js

@@ -15,6 +15,7 @@
  * ```
  */
 import { Flags } from '@oclif/core';
+import { parseDuration } from './duration.js';
 /**
  * Agent, Task, and Provider flags for customizing command behavior
  *
@@ -44,9 +45,17 @@ export const agentFlags = {
         description: 'Override which task command to execute (e.g., develop-story, draft, review-implementation). Defaults to command-appropriate task.',
         helpGroup: 'Agent Customization',
     }),
-    timeout: Flags.integer({
+    timeout: Flags.custom({
+        parse: async (input) => parseDuration(input),
+    })({
         default: 2_700_000,
-        description: 'Agent execution timeout in milliseconds (default: 2700000 = 45 minutes)',
+        description: 'Agent execution timeout — accepts durations like 30s, 5m, 1h, 90m, or raw milliseconds (default: 45m)',
+        helpGroup: 'Resilience',
+    }),
+    'review-timeout': Flags.custom({
+        parse: async (input) => parseDuration(input),
+    })({
+        description: 'AI review scanner timeout — overrides --timeout for review phase only (default: 5m)',
         helpGroup: 'Resilience',
     }),
     'max-retries': Flags.integer({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hyperdrive.bot/bmad-workflow",
   "description": "AI-driven development workflow orchestration CLI for BMAD projects",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "author": {
     "name": "DevSquad",
     "email": "marcelo@devsquad.email",
@@ -14,6 +14,7 @@
     "url": "https://gitlab.com/dev_squad/repo/cli/bmad-orchestrator/issues"
   },
   "dependencies": {
+    "@hyperdrive.bot/plugin-telemetry": "file:../telemetry-plugin",
     "@oclif/core": "^4",
     "@oclif/plugin-help": "^6",
     "bcrypt": "^6.0.0",
@@ -89,7 +90,8 @@
     "dirname": "bmad-workflow",
     "commands": "./dist/commands",
     "plugins": [
-      "@oclif/plugin-help"
+      "@oclif/plugin-help",
+      "@hyperdrive.bot/plugin-telemetry"
     ],
     "topicSeparator": " "
   },