@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/gates/README.md

@@ -0,0 +1,374 @@
+# Quality Gate Implementation Guide
+
+This guide explains how to implement quality gates using the Quality Gate Coordinator.
+
+## Overview
+
+The Quality Gate Coordinator provides a central registry and execution engine for quality gates. Each gate:
+
+1. **Validates input** using Zod schemas
+2. **Executes checks** via a custom executor function
+3. **Returns structured results** with pass/fail status, errors, and warnings
+4. **Supports bypass** with mandatory audit trail
+
+## API Reference
+
+### `registerGate(id, schema, executor)`
+
+Registers a new quality gate.
+
+**Parameters:**
+- `id` (string): Unique gate identifier (e.g., `"requirement-completeness"`)
+- `schema` (ZodSchema): Zod schema for validating gate context
+- `executor` (Function): Async function that executes the gate logic
+
+**Example:**
+```javascript
+const { QualityGate, z } = require('./quality-gate.cjs');
+
+const gates = new QualityGate();
+
+gates.registerGate(
+  'requirement-completeness',
+  z.object({
+    requirements: z.array(z.object({
+      id: z.string(),
+      description: z.string(),
+      acceptanceCriteria: z.array(z.string()),
+    })),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    for (const req of context.requirements) {
+      if (!req.id || req.id.length === 0) {
+        errors.push({ path: 'requirements[].id', message: 'Requirement ID is required' });
+      }
+      if (req.acceptanceCriteria.length === 0) {
+        warnings.push(`Requirement ${req.id} has no acceptance criteria`);
+      }
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+### `executeGate(id, context)`
+
+Executes a registered gate with the provided context.
+
+**Parameters:**
+- `id` (string): Gate identifier
+- `context` (any): Context data to validate and pass to executor
+
+**Returns:** `Promise<ExecutionResult>`
+```javascript
+{
+  passed: boolean,
+  errors: Array<{ path: string, message: string }>,
+  warnings: Array<string>,
+}
+```
+
+**Example:**
+```javascript
+const result = await gates.executeGate('requirement-completeness', {
+  requirements: [
+    {
+      id: 'REQ-001',
+      description: 'User can log in',
+      acceptanceCriteria: ['Given valid credentials', 'When login form submitted', 'Then user is authenticated'],
+    },
+  ],
+});
+
+if (result.passed) {
+  console.log('Gate passed!');
+} else {
+  console.error('Gate failed:', result.errors);
+}
+```
+
+### `bypassGate(id, reason)`
+
+Bypasses a gate with a mandatory audit reason.
+
+**Parameters:**
+- `id` (string): Gate identifier
+- `reason` (string): Non-empty reason for bypass (logged to audit trail)
+
+**Example:**
+```javascript
+// Bypass with explicit reason (required)
+gates.bypassGate('security-baseline', 'MVP tier - security audit deferred to Phase 40');
+
+// This will throw an error (empty reason not allowed)
+gates.bypassGate('security-baseline', ''); // Error!
+```
+
+### `getGateStatus(id)`
+
+Returns the current status of a gate.
+
+**Parameters:**
+- `id` (string): Gate identifier
+
+**Returns:** `GateStatus`
+```javascript
+{
+  state: 'registered' | 'passed' | 'failed' | 'bypassed',
+  id: string,
+  registeredAt?: Date,
+  executedAt?: Date,
+  bypassedAt?: Date,
+  bypassReason?: string,
+  errors?: Array<{ path: string, message: string }>,
+  warnings?: Array<string>,
+}
+```
+
+**Example:**
+```javascript
+const status = gates.getGateStatus('requirement-completeness');
+console.log(`Gate state: ${status.state}`);
+```
+
+## Gate Implementation Patterns
+
+### Pattern 1: Simple Validation Gate
+
+```javascript
+gates.registerGate(
+  'plan-completeness',
+  z.object({
+    tasks: z.array(z.object({
+      id: z.string(),
+      name: z.string(),
+      action: z.string(),
+    })),
+  }),
+  async (context) => {
+    const errors = [];
+
+    if (context.tasks.length === 0) {
+      errors.push({ path: 'tasks', message: 'At least one task is required' });
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  }
+);
+```
+
+### Pattern 2: Multi-Check Gate
+
+```javascript
+gates.registerGate(
+  'code-quality',
+  z.object({
+    files: z.array(z.string()),
+    metrics: z.object({
+      complexity: z.number(),
+      coverage: z.number(),
+    }),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    // Check 1: Complexity threshold
+    if (context.metrics.complexity > 10) {
+      errors.push({ path: 'metrics.complexity', message: 'Cyclomatic complexity exceeds threshold (10)' });
+    }
+
+    // Check 2: Test coverage
+    if (context.metrics.coverage < 80) {
+      warnings.push(`Test coverage is ${context.metrics.coverage}%, recommended: 80%`);
+    }
+
+    // Check 3: File count
+    if (context.files.length > 50) {
+      warnings.push(`Large change set: ${context.files.length} files modified`);
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+### Pattern 3: External Tool Integration Gate
+
+```javascript
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
+
+gates.registerGate(
+  'security-scan',
+  z.object({
+    projectPath: z.string(),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    try {
+      // Run npm audit
+      const { stdout } = await execAsync('npm audit --json', {
+        cwd: context.projectPath,
+      });
+      const audit = JSON.parse(stdout);
+
+      if (audit.metadata.vulnerabilities.critical > 0) {
+        errors.push({
+          path: 'dependencies',
+          message: `Found ${audit.metadata.vulnerabilities.critical} critical vulnerabilities`,
+        });
+      }
+
+      if (audit.metadata.vulnerabilities.high > 0) {
+        warnings.push(`Found ${audit.metadata.vulnerabilities.high} high severity vulnerabilities`);
+      }
+    } catch (err) {
+      if (err.stdout) {
+        const audit = JSON.parse(err.stdout);
+        if (audit.metadata.vulnerabilities.total > 0) {
+          warnings.push(`npm audit found ${audit.metadata.vulnerabilities.total} vulnerabilities`);
+        }
+      } else {
+        warnings.push('Could not run npm audit');
+      }
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+## Audit Trail
+
+All gate bypasses are logged to `.planning/gate-audit.json`:
+
+```json
+[
+  {
+    "gateId": "security-baseline",
+    "action": "bypass",
+    "reason": "MVP tier - security audit deferred to Phase 40",
+    "timestamp": "2026-03-21T10:30:00.000Z"
+  }
+]
+```
+
+## Error Handling
+
+### Schema Validation Errors
+
+When context fails schema validation, errors include field paths:
+
+```javascript
+const result = await gates.executeGate('requirement-completeness', {
+  requirements: [
+    { id: '', description: 'Test' }, // Missing ID
+  ],
+});
+
+// result.errors:
+// [
+//   { path: 'requirements.0.id', message: 'Required' },
+// ]
+```
+
+### Executor Errors
+
+If the executor throws an exception, it's caught and returned as an error:
+
+```javascript
+gates.registerGate(
+  'flaky-gate',
+  z.object({}),
+  async () => {
+    throw new Error('Something went wrong');
+  }
+);
+
+const result = await gates.executeGate('flaky-gate', {});
+// result.passed: false
+// result.errors: [{ path: 'executor', message: 'Something went wrong' }]
+```
+
+### Unregistered Gate
+
+Executing an unregistered gate throws an error:
+
+```javascript
+await gates.executeGate('nonexistent-gate', {});
+// Throws: Error: Gate not registered: nonexistent-gate
+```
+
+## Best Practices
+
+1. **Use descriptive gate IDs**: `requirement-completeness` not `gate1`
+2. **Define strict schemas**: Validate all required fields with Zod
+3. **Return structured errors**: Include field paths for easy debugging
+4. **Use warnings for non-blocking issues**: Distinguish between errors (block) and warnings (inform)
+5. **Document bypass reasons**: Always provide clear, actionable bypass reasons
+6. **Keep executors focused**: Each gate should check one quality dimension
+7. **Test gates independently**: Write unit tests for each gate executor
+
+## Integration with Phase Execution
+
+```javascript
+const { QualityGate, z } = require('./quality-gate.cjs');
+
+async function executePhase(phasePlan) {
+  const gates = new QualityGate();
+
+  // Register gates
+  gates.registerGate(/* ... */);
+
+  // Execute pre-execution gates
+  const preCheck = await gates.executeGate('plan-completeness', phasePlan);
+  if (!preCheck.passed) {
+    throw new Error(`Pre-check failed: ${JSON.stringify(preCheck.errors)}`);
+  }
+
+  // Execute phase tasks...
+
+  // Execute post-execution gates
+  const postCheck = await gates.executeGate('verification-complete', {
+    tasks: phasePlan.tasks,
+    summaries: taskSummaries,
+  });
+
+  if (!postCheck.passed) {
+    // Trigger gap closure workflow
+    console.error('Post-check failed:', postCheck.errors);
+  }
+
+  return postCheck;
+}
+```
+
+## See Also
+
+- Phase 34-03: Gate 1-2 Implementation (Requirement Completeness, Architecture Review)
+- Phase 34-04: Gate 3-4 Implementation (Code Quality, Security Baseline)
+- Phase 40: Gates 5-7 (Testing, Documentation, Release)

package/ez-agents/bin/lib/gates/gate-01-requirement.cjs

@@ -0,0 +1,303 @@
+/**
+ * Gate 1: Requirement Completeness
+ *
+ * Validates that all requirements are properly mapped to tasks/phases
+ * and have clear acceptance criteria in Given-When-Then format.
+ *
+ * Checks:
+ * 1. All REQ-IDs are mapped to tasks or phases
+ * 2. Acceptance criteria exist and follow Given-When-Then format
+ * 3. Returns structured errors for unmapped or incomplete requirements
+ *
+ * @module gates/gate-01-requirement
+ */
+
+const { z } = require('zod');
+
+/**
+ * Zod schema for a single requirement
+ * @type {z.ZodSchema}
+ */
+const requirementSchema = z.object({
+  /** Unique requirement identifier (e.g., 'REQ-001', 'GRAPH-01') */
+  id: z.string().min(1, 'Requirement ID is required'),
+  /** Human-readable requirement description */
+  description: z.string().min(1, 'Requirement description is required'),
+  /** Acceptance criteria array (each should follow Given-When-Then format) */
+  acceptanceCriteria: z.array(z.string()).min(1, 'At least one acceptance criterion is required'),
+  /** Optional: Array of task IDs that implement this requirement */
+  mappedTasks: z.array(z.string()).optional(),
+  /** Optional: Array of phase IDs that cover this requirement */
+  mappedPhases: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for a single task
+ * @type {z.ZodSchema}
+ */
+const taskSchema = z.object({
+  /** Unique task identifier */
+  id: z.string(),
+  /** Task name/title */
+  name: z.string(),
+  /** Optional: Requirements this task addresses */
+  requirements: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for a single phase
+ * @type {z.ZodSchema}
+ */
+const phaseSchema = z.object({
+  /** Unique phase identifier */
+  id: z.string(),
+  /** Phase name/title */
+  name: z.string(),
+  /** Optional: Requirements this phase covers */
+  requirements: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for the gate context
+ * @type {z.ZodSchema}
+ */
+const gateContextSchema = z.object({
+  /** Array of all requirements to validate */
+  requirements: z.array(requirementSchema),
+  /** Optional: Array of tasks for mapping validation */
+  tasks: z.array(taskSchema).optional(),
+  /** Optional: Array of phases for mapping validation */
+  phases: z.array(phaseSchema).optional(),
+});
+
+/**
+ * Check if acceptance criteria follow Given-When-Then format
+ *
+ * Accepts variations:
+ * - "Given X, When Y, Then Z" (single line)
+ * - "Given X\nWhen Y\nThen Z" (multi-line)
+ * - "Given: X\nWhen: Y\nThen: Z" (with colons)
+ * - Separate "Given...", "When...", "Then..." entries
+ *
+ * @param {string[]} acceptanceCriteria - Array of acceptance criteria strings
+ * @returns {{ valid: boolean, missingComponents: string[], suggestion: string }}
+ */
+function checkGivenWhenThenFormat(acceptanceCriteria) {
+  const result = {
+    valid: true,
+    missingComponents: [],
+    suggestion: '',
+  };
+
+  if (!acceptanceCriteria || acceptanceCriteria.length === 0) {
+    result.valid = false;
+    result.missingComponents = ['Given', 'When', 'Then'];
+    result.suggestion = 'Add acceptance criteria in Given-When-Then format';
+    return result;
+  }
+
+  // Combine all criteria into single text for analysis
+  const fullText = acceptanceCriteria.join('\n').toLowerCase();
+
+  // Check for Given-When-Then components
+  const hasGiven = /given[:\s]/.test(fullText);
+  const hasWhen = /when[:\s]/.test(fullText);
+  const hasThen = /then[:\s]/.test(fullText);
+
+  if (!hasGiven) {
+    result.missingComponents.push('Given');
+  }
+  if (!hasWhen) {
+    result.missingComponents.push('When');
+  }
+  if (!hasThen) {
+    result.missingComponents.push('Then');
+  }
+
+  if (result.missingComponents.length > 0) {
+    result.valid = false;
+    result.suggestion = `Missing BDD components: ${result.missingComponents.join(', ')}. ` +
+      'Format: "Given [context], When [action], Then [expected outcome]"';
+  }
+
+  return result;
+}
+
+/**
+ * Extract REQ-IDs from a text string
+ * Matches patterns like: REQ-001, GRAPH-02, GATE-01, etc.
+ *
+ * @param {string} text - Text to search for requirement IDs
+ * @returns {string[]} Array of found requirement IDs
+ */
+function extractRequirementIds(text) {
+  if (!text) return [];
+
+  // Match patterns like REQ-001, GRAPH-02, GATE-01, etc.
+  const pattern = /\b([A-Z]+-\d+)\b/g;
+  const matches = text.match(pattern);
+  return matches ? [...new Set(matches)] : [];
+}
+
+/**
+ * Build a map of requirement IDs to their mappings from tasks
+ *
+ * @param {Array} tasks - Array of task objects
+ * @returns {Map<string, Set<string>>} Map of reqId -> Set of task IDs
+ */
+function buildRequirementTaskMap(tasks) {
+  const map = new Map();
+
+  if (!tasks || !Array.isArray(tasks)) {
+    return map;
+  }
+
+  for (const task of tasks) {
+    const reqs = task.requirements || [];
+    for (const reqId of reqs) {
+      if (!map.has(reqId)) {
+        map.set(reqId, new Set());
+      }
+      map.get(reqId).add(task.id);
+    }
+
+    // Also check task name and description for implicit references
+    const implicitRefs = extractRequirementIds(`${task.name} ${task.description || ''}`);
+    for (const reqId of implicitRefs) {
+      if (!map.has(reqId)) {
+        map.set(reqId, new Set());
+      }
+      map.get(reqId).add(task.id);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Build a map of requirement IDs to their mappings from phases
+ *
+ * @param {Array} phases - Array of phase objects
+ * @returns {Map<string, Set<string>>} Map of reqId -> Set of phase IDs
+ */
+function buildRequirementPhaseMap(phases) {
+  const map = new Map();
+
+  if (!phases || !Array.isArray(phases)) {
+    return map;
+  }
+
+  for (const phase of phases) {
+    const reqs = phase.requirements || [];
+    for (const reqId of reqs) {
+      if (!map.has(reqId)) {
+        map.set(reqId, new Set());
+      }
+      map.get(reqId).add(phase.id);
+    }
+
+    // Also check phase name and description for implicit references
+    const implicitRefs = extractRequirementIds(`${phase.name} ${phase.description || ''}`);
+    for (const reqId of implicitRefs) {
+      if (!map.has(reqId)) {
+        map.set(reqId, new Set());
+      }
+      map.get(reqId).add(phase.id);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Gate 1 Executor: Requirement Completeness Check
+ *
+ * Validates:
+ * 1. All requirements have mapped tasks or phases
+ * 2. All requirements have acceptance criteria in Given-When-Then format
+ *
+ * @param {Object} context - Gate context (validated against gateContextSchema)
+ * @param {Array} context.requirements - Array of requirement objects
+ * @param {Array} [context.tasks] - Optional array of task objects
+ * @param {Array} [context.phases] - Optional array of phase objects
+ * @returns {Promise<{ passed: boolean, errors: Array<{path: string, message: string}>, warnings: string[] }>}
+ */
+async function executeGate1(context) {
+  const errors = [];
+  const warnings = [];
+
+  // Build mapping indices
+  const taskMap = buildRequirementTaskMap(context.tasks);
+  const phaseMap = buildRequirementPhaseMap(context.phases);
+
+  // Check each requirement
+  for (let i = 0; i < context.requirements.length; i++) {
+    const req = context.requirements[i];
+    const reqPath = `requirements[${i}]`;
+
+    // Check 1: Requirement mapping
+    const mappedToTasks = taskMap.has(req.id);
+    const mappedToPhases = phaseMap.has(req.id);
+    const hasExplicitMapping = (req.mappedTasks && req.mappedTasks.length > 0) ||
+                               (req.mappedPhases && req.mappedPhases.length > 0);
+
+    if (!mappedToTasks && !mappedToPhases && !hasExplicitMapping) {
+      errors.push({
+        path: `${reqPath}.id`,
+        message: `Requirement '${req.id}' is not mapped to any task or phase. ` +
+          `Add 'requirements: ["${req.id}"]' to a task/phase frontmatter or ` +
+          `add explicit mappedTasks/mappedPhases array.`,
+      });
+    }
+
+    // Check 2: Acceptance criteria format
+    const formatCheck = checkGivenWhenThenFormat(req.acceptanceCriteria);
+    if (!formatCheck.valid) {
+      errors.push({
+        path: `${reqPath}.acceptanceCriteria`,
+        message: `Requirement '${req.id}' has acceptance criteria that don't follow ` +
+          `Given-When-Then format. ${formatCheck.suggestion}`,
+      });
+    }
+
+    // Check 3: Acceptance criteria specificity (warning)
+    for (let j = 0; j < req.acceptanceCriteria.length; j++) {
+      const criterion = req.acceptanceCriteria[j];
+      if (criterion.length < 20) {
+        warnings.push(
+          `${reqPath}.acceptanceCriteria[${j}]: Criterion for '${req.id}' is very short ` +
+          `(${criterion.length} chars). Consider adding more specific, testable criteria.`
+        );
+      }
+    }
+  }
+
+  return {
+    passed: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Create and register Gate 1 with a QualityGate instance
+ *
+ * @param {QualityGate} gateCoordinator - QualityGate coordinator instance
+ * @returns {void}
+ */
+function registerGate1(gateCoordinator) {
+  gateCoordinator.registerGate('gate-01-requirement', gateContextSchema, executeGate1);
+}
+
+module.exports = {
+  executeGate1,
+  registerGate1,
+  requirementSchema,
+  taskSchema,
+  phaseSchema,
+  gateContextSchema,
+  checkGivenWhenThenFormat,
+  extractRequirementIds,
+  buildRequirementTaskMap,
+  buildRequirementPhaseMap,
+};