@odavl/guardian 0.1.0-rc1

package/src/guardian/attempt-engine.js

@@ -0,0 +1,454 @@
+/**
+ * Guardian Attempt Engine - PHASE 1 + PHASE 2
+ * Executes a single user attempt and tracks outcome (SUCCESS, FAILURE, FRICTION)
+ * Phase 2: Soft failure detection via validators
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getAttemptDefinition } = require('./attempt-registry');
+const { runValidators, analyzeSoftFailures } = require('./validators');
+
+class AttemptEngine {
+  constructor(options = {}) {
+    this.attemptId = options.attemptId || 'default';
+    this.timeout = options.timeout || 30000;
+    this.frictionThresholds = options.frictionThresholds || {
+      totalDurationMs: 2500, // Total attempt > 2.5s
+      stepDurationMs: 1500,   // Any single step > 1.5s
+      retryCount: 1            // More than 1 retry = friction
+    };
+  }
+
+  /**
+   * Load attempt definition by ID (Phase 3 registry)
+   */
+  loadAttemptDefinition(attemptId) {
+    return getAttemptDefinition(attemptId);
+  }
+
+  /**
+   * Execute a single attempt
+   * Returns: { outcome, steps, timings, friction, error, validators, softFailures }
+   */
+  async executeAttempt(page, attemptId, baseUrl, artifactsDir = null, validatorSpecs = null) {
+    const attemptDef = this.loadAttemptDefinition(attemptId);
+    if (!attemptDef) {
+      throw new Error(`Attempt ${attemptId} not found`);
+    }
+
+    const startedAt = new Date();
+    const steps = [];
+    const frictionSignals = [];
+    const consoleMessages = []; // Capture console messages for validators
+    let currentStep = null;
+    let lastError = null;
+    let frictionReasons = [];
+    let frictionMetrics = {};
+
+    // Capture console messages for soft failure detection
+    const consoleHandler = (msg) => {
+      consoleMessages.push({
+        type: msg.type(), // 'log', 'error', 'warning', etc.
+        text: msg.text(),
+        location: msg.location()
+      });
+    };
+
+    page.on('console', consoleHandler);
+
+    try {
+      // Replace $BASEURL placeholder in all steps
+      const processedSteps = attemptDef.baseSteps.map(step => {
+        if (step.target && step.target === '$BASEURL') {
+          return { ...step, target: baseUrl };
+        }
+        return step;
+      });
+
+      // Execute each step
+      for (const stepDef of processedSteps) {
+        currentStep = {
+          id: stepDef.id,
+          type: stepDef.type,
+          target: stepDef.target,
+          description: stepDef.description,
+          startedAt: new Date().toISOString(),
+          retries: 0,
+          status: 'pending',
+          error: null,
+          screenshots: []
+        };
+
+        const stepStartTime = Date.now();
+
+        try {
+          // Execute with retry logic (up to 2 attempts)
+          let success = false;
+          for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+              if (attempt > 0) {
+                currentStep.retries++;
+                // Small backoff before retry
+                await page.waitForTimeout(200);
+              }
+
+              await this._executeStep(page, stepDef);
+              success = true;
+              break;
+            } catch (err) {
+              if (attempt === 1) {
+                throw err; // Final attempt failed
+              }
+              // Retry on first failure
+            }
+          }
+
+          const stepEndTime = Date.now();
+          const stepDurationMs = stepEndTime - stepStartTime;
+
+          currentStep.endedAt = new Date().toISOString();
+          currentStep.durationMs = stepDurationMs;
+          currentStep.status = 'success';
+
+          // Check for friction signals in step timing
+          if (stepDurationMs > this.frictionThresholds.stepDurationMs) {
+            frictionSignals.push({
+              id: 'slow_step_execution',
+              description: `Step took longer than threshold`,
+              metric: 'stepDurationMs',
+              threshold: this.frictionThresholds.stepDurationMs,
+              observedValue: stepDurationMs,
+              affectedStepId: stepDef.id,
+              severity: 'medium'
+            });
+            frictionReasons.push(`Step "${stepDef.id}" took ${stepDurationMs}ms (threshold: ${this.frictionThresholds.stepDurationMs}ms)`);
+          }
+
+          if (currentStep.retries > this.frictionThresholds.retryCount) {
+            frictionSignals.push({
+              id: 'multiple_retries_required',
+              description: `Step required multiple retry attempts`,
+              metric: 'retryCount',
+              threshold: this.frictionThresholds.retryCount,
+              observedValue: currentStep.retries,
+              affectedStepId: stepDef.id,
+              severity: 'high'
+            });
+            frictionReasons.push(`Step "${stepDef.id}" required ${currentStep.retries} retries`);
+          }
+
+          // Capture screenshot on success if artifacts dir provided
+          if (artifactsDir) {
+            const screenshotPath = await this._captureScreenshot(
+              page,
+              artifactsDir,
+              stepDef.id
+            );
+            if (screenshotPath) {
+              currentStep.screenshots.push(screenshotPath);
+            }
+          }
+
+        } catch (err) {
+          currentStep.endedAt = new Date().toISOString();
+          currentStep.durationMs = Date.now() - stepStartTime;
+          currentStep.status = stepDef.optional ? 'skipped' : 'failed';
+          currentStep.error = err.message;
+
+          if (stepDef.optional) {
+            // Optional steps should not fail the attempt; record and move on
+            steps.push(currentStep);
+            continue;
+          }
+
+          lastError = err;
+
+          // Capture screenshot on failure
+          if (artifactsDir) {
+            const screenshotPath = await this._captureScreenshot(
+              page,
+              artifactsDir,
+              `${stepDef.id}_failure`
+            );
+            if (screenshotPath) {
+              currentStep.screenshots.push(screenshotPath);
+            }
+          }
+
+          throw err; // Stop attempt on step failure
+        }
+
+        steps.push(currentStep);
+      }
+
+      // All steps successful, now check success conditions
+      const endedAt = new Date();
+      const totalDurationMs = endedAt.getTime() - startedAt.getTime();
+
+      // Check success conditions
+      let successMet = false;
+      let successReason = null;
+
+      for (const condition of attemptDef.successConditions) {
+        try {
+          if (condition.type === 'url') {
+            const currentUrl = page.url();
+            if (condition.pattern.test(currentUrl)) {
+              successMet = true;
+              successReason = `URL matched: ${currentUrl}`;
+              break;
+            }
+          } else if (condition.type === 'selector') {
+            // Wait briefly for selector to become visible
+            try {
+              await page.waitForSelector(condition.target, { timeout: 3000, state: 'visible' });
+              successMet = true;
+              successReason = `Success element visible: ${condition.target}`;
+              break;
+            } catch (e) {
+              // Continue to next condition
+            }
+          }
+        } catch (err) {
+          // Continue to next condition
+        }
+      }
+
+      if (!successMet) {
+        page.removeListener('console', consoleHandler);
+        return {
+          outcome: 'FAILURE',
+          steps,
+          startedAt: startedAt.toISOString(),
+          endedAt: endedAt.toISOString(),
+          totalDurationMs,
+          friction: {
+            isFriction: false,
+            signals: [],
+            summary: null,
+            reasons: [],
+            thresholds: this.frictionThresholds,
+            metrics: {}
+          },
+          error: 'Success conditions not met after all steps completed',
+          successReason: null,
+          validators: [],
+          softFailures: { hasSoftFailure: false, failureCount: 0, warnCount: 0 }
+        };
+      }
+
+      // Run validators for soft failure detection (Phase 2)
+      let validatorResults = [];
+      let softFailureAnalysis = { hasSoftFailure: false, failureCount: 0, warnCount: 0 };
+
+      if (validatorSpecs && validatorSpecs.length > 0) {
+        const validatorContext = {
+          page,
+          consoleMessages,
+          url: page.url()
+        };
+
+        validatorResults = await runValidators(validatorSpecs, validatorContext);
+        softFailureAnalysis = analyzeSoftFailures(validatorResults);
+
+        // If validators detected soft failures, upgrade outcome
+        if (softFailureAnalysis.hasSoftFailure) {
+          // Soft failure still counts as FAILURE (outcome), not FRICTION
+          // Soft failures are recorded separately for analysis
+        }
+      }
+
+      // Check for friction signals in total duration
+      if (totalDurationMs > this.frictionThresholds.totalDurationMs) {
+        frictionSignals.push({
+          id: 'slow_total_duration',
+          description: `Total attempt duration exceeded threshold`,
+          metric: 'totalDurationMs',
+          threshold: this.frictionThresholds.totalDurationMs,
+          observedValue: totalDurationMs,
+          affectedStepId: null,
+          severity: 'low'
+        });
+        frictionReasons.push(`Attempt took ${totalDurationMs}ms total (threshold: ${this.frictionThresholds.totalDurationMs}ms)`);
+      }
+
+      frictionMetrics = {
+        totalDurationMs,
+        stepCount: steps.length,
+        totalRetries: steps.reduce((sum, s) => sum + s.retries, 0),
+        maxStepDurationMs: Math.max(...steps.map(s => s.durationMs || 0))
+      };
+
+      // Determine outcome based on friction signals
+      const isFriction = frictionSignals.length > 0;
+      const outcome = isFriction ? 'FRICTION' : 'SUCCESS';
+
+      // Generate friction summary
+      const frictionSummary = isFriction 
+        ? `User succeeded, but encountered ${frictionSignals.length} friction ${frictionSignals.length === 1 ? 'signal' : 'signals'}` 
+        : null;
+
+      return {
+        outcome,
+        steps,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        totalDurationMs,
+        friction: {
+          isFriction,
+          signals: frictionSignals,
+          summary: frictionSummary,
+          reasons: frictionReasons, // Keep for backward compatibility
+          thresholds: this.frictionThresholds,
+          metrics: frictionMetrics
+        },
+        error: null,
+        successReason,
+        validators: validatorResults,
+        softFailures: softFailureAnalysis
+      };
+
+    } catch (err) {
+      const endedAt = new Date();
+      page.removeListener('console', consoleHandler);
+      return {
+        outcome: 'FAILURE',
+        steps,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        totalDurationMs: endedAt.getTime() - startedAt.getTime(),
+        friction: {
+          isFriction: false,
+          reasons: [],
+          thresholds: this.frictionThresholds,
+          metrics: {}
+        },
+        error: `Step "${currentStep?.id}" failed: ${err.message}`,
+        successReason: null,
+        validators: [],
+        softFailures: { hasSoftFailure: false, failureCount: 0, warnCount: 0 }
+      };
+    } finally {
+      page.removeListener('console', consoleHandler);
+    }
+  }
+
+  /**
+   * Execute a single step
+   */
+  async _executeStep(page, stepDef) {
+    const timeout = stepDef.timeout || this.timeout;
+
+    switch (stepDef.type) {
+      case 'navigate':
+        await page.goto(stepDef.target, {
+          waitUntil: 'domcontentloaded',
+          timeout
+        });
+        break;
+
+      case 'click':
+        // Try each selector in the target (semicolon-separated)
+        const selectors = stepDef.target.split(',').map(s => s.trim());
+        let clicked = false;
+
+        for (const selector of selectors) {
+          try {
+            await page.click(selector, { timeout: 5000 });
+            clicked = true;
+            break;
+          } catch (err) {
+            // Try next selector
+          }
+        }
+
+        if (!clicked) {
+          throw new Error(`Could not click element: ${stepDef.target}`);
+        }
+
+        // Wait for navigation if expected
+        if (stepDef.waitForNavigation) {
+          await page.waitForLoadState('domcontentloaded').catch(() => {});
+        }
+        break;
+
+      case 'type':
+        // Try each selector
+        const typeSelectors = stepDef.target.split(',').map(s => s.trim());
+        let typed = false;
+
+        for (const selector of typeSelectors) {
+          try {
+            await page.fill(selector, stepDef.value, { timeout: 5000 });
+            typed = true;
+            break;
+          } catch (err) {
+            // Try next selector
+          }
+        }
+
+        if (!typed) {
+          throw new Error(`Could not type into element: ${stepDef.target}`);
+        }
+        break;
+
+      case 'waitFor':
+        const waitSelectors = stepDef.target.split(',').map(s => s.trim());
+        let found = false;
+
+        for (const selector of waitSelectors) {
+          try {
+            await page.waitForSelector(selector, {
+              timeout: stepDef.timeout || 5000,
+              state: stepDef.state || 'visible'
+            });
+            found = true;
+            break;
+          } catch (err) {
+            // Try next selector
+          }
+        }
+
+        if (!found) {
+          throw new Error(`Element not found: ${stepDef.target}`);
+        }
+        break;
+
+      case 'wait':
+        await page.waitForTimeout(stepDef.duration || 1000);
+        break;
+
+      default:
+        throw new Error(`Unknown step type: ${stepDef.type}`);
+    }
+  }
+
+  /**
+   * Capture screenshot
+   */
+  async _captureScreenshot(page, artifactsDir, stepId) {
+    try {
+      const screenshotsDir = path.join(artifactsDir, 'attempt-screenshots');
+      if (!fs.existsSync(screenshotsDir)) {
+        fs.mkdirSync(screenshotsDir, { recursive: true });
+      }
+
+      const filename = `${stepId}.jpeg`;
+      const fullPath = path.join(screenshotsDir, filename);
+
+      await page.screenshot({
+        path: fullPath,
+        type: 'jpeg',
+        quality: 80,
+        fullPage: true
+      });
+
+      return filename;
+    } catch (err) {
+      return null;
+    }
+  }
+}
+
+module.exports = { AttemptEngine };

package/src/guardian/attempt-registry.js

@@ -0,0 +1,227 @@
+/**
+ * Central registry for attempt definitions
+ * Phase 3: supports multiple curated attempts
+ */
+
+const DEFAULT_ATTEMPTS = ['contact_form', 'language_switch', 'newsletter_signup', 'signup', 'login', 'checkout'];
+
+const attemptDefinitions = {
+  contact_form: {
+    id: 'contact_form',
+    name: 'Contact Form Submission',
+    goal: 'User submits the contact form successfully',
+    riskCategory: 'LEAD',
+    baseSteps: [
+      { id: 'navigate_form', type: 'navigate', target: '$BASEURL', description: 'Navigate to contact form' },
+      {
+        id: 'open_contact_page',
+        type: 'click',
+        target: 'a[data-guardian="contact-link"], a[data-testid="contact-link"], a:has-text("Contact"), a[href*="/contact"]',
+        description: 'Open contact page',
+        optional: true,
+        waitForNavigation: true
+      },
+      { id: 'fill_name', type: 'type', target: 'input[name="name"], input[data-testid="name"], input[data-guardian="name"]', value: 'Test User', description: 'Enter name', timeout: 5000 },
+      { id: 'fill_email', type: 'type', target: 'input[name="email"], input[data-testid="email"], input[type="email"], input[data-guardian="email"]', value: 'test@example.com', description: 'Enter email', timeout: 5000 },
+      { id: 'fill_message', type: 'type', target: 'textarea[name="message"], textarea[data-testid="message"], input[name="message"], textarea[data-guardian="message"]', value: 'This is a test message.', description: 'Enter message', timeout: 5000 },
+      { id: 'submit_form', type: 'click', target: 'button[type="submit"], button:has-text("Submit"), button:has-text("Send"), button[data-guardian="submit"]', description: 'Submit form', timeout: 5000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="success"], [data-testid="success"]', description: 'Success message element visible' }
+    ],
+    // Phase 2: Soft failure validators
+    validators: [
+      // Success indicators
+      { type: 'elementVisible', selector: '[data-guardian="success"], [data-testid="success"], .success-message, .alert-success' },
+      { type: 'pageContainsAnyText', textList: ['success', 'submitted', 'thank you', 'message received'] },
+      // Error/failure indicators that would make this a SOFT FAILURE
+      { type: 'elementNotVisible', selector: '.error, [role="alert"], .form-error, .error-message' }
+    ]
+  },
+
+  language_switch: {
+    id: 'language_switch',
+    name: 'Language Toggle',
+    goal: 'User switches language successfully',
+    riskCategory: 'TRUST/UX',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      { id: 'open_language_page', type: 'click', target: 'a[data-guardian="language-link"], a:has-text("Language Switch")', description: 'Open language switch page', timeout: 5000 },
+      { id: 'open_language_toggle', type: 'click', target: '[data-guardian="lang-toggle"], button:has-text("Language"), button:has-text("Lang")', description: 'Open language toggle', timeout: 5000 },
+      { id: 'select_language', type: 'click', target: '[data-guardian="lang-option-de"], [data-testid="lang-option-de"], button:has-text("DE")', description: 'Switch to German', timeout: 5000 },
+      { id: 'verify_language', type: 'waitFor', target: '[data-guardian="lang-current"]:has-text("DE")', description: 'Wait for language to switch to DE', timeout: 5000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="lang-current"]:has-text("DE")', description: 'Current language shows DE' },
+      { type: 'selector', target: '[data-guardian="lang-current"], [data-testid="lang-current"]', description: 'Language indicator visible' }
+    ],
+    // Phase 2: Language switch validators
+    validators: [
+      { type: 'htmlLangAttribute', lang: 'de' },
+      { type: 'pageContainsAnyText', textList: ['Deutsch', 'German', 'Sprache'] }
+    ]
+  },
+
+  newsletter_signup: {
+    id: 'newsletter_signup',
+    name: 'Newsletter Signup',
+    goal: 'User signs up for newsletter',
+    riskCategory: 'LEAD',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      {
+        id: 'open_signup_page',
+        type: 'click',
+        target: 'a[data-guardian="signup-link"], a[data-testid="signup-link"], a:has-text("Sign up"), a:has-text("Signup"), a[href*="signup"], a[href*="newsletter"]',
+        description: 'Open signup page',
+        optional: true,
+        waitForNavigation: true
+      },
+      { id: 'fill_email', type: 'type', target: 'input[type="email"], input[data-guardian="signup-email"], input[data-testid="signup-email"]', value: 'subscriber@example.com', description: 'Enter email', timeout: 5000 },
+      { id: 'submit_signup', type: 'click', target: 'button[type="submit"], button[data-guardian="signup-submit"], button:has-text("Subscribe"), button:has-text("Sign up")', description: 'Submit signup', timeout: 5000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="signup-success"], [data-testid="signup-success"]', description: 'Signup success message visible' }
+    ],
+    // Phase 2: Newsletter signup validators
+    validators: [
+      { type: 'elementVisible', selector: '[data-guardian="signup-success"], [data-testid="signup-success"], .signup-success, .toast-success' },
+      { type: 'pageContainsAnyText', textList: ['confirmed', 'subscribed', 'thank you', 'welcome', 'subscription'] },
+      { type: 'elementNotVisible', selector: '.error, [role="alert"], .signup-error, .error-message' }
+    ]
+  },
+
+  signup: {
+    id: 'signup',
+    name: 'Account Signup',
+    goal: 'User creates an account successfully',
+    riskCategory: 'LEAD',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      { id: 'open_account_signup', type: 'click', target: 'a[data-guardian="account-signup-link"], a:has-text("Account Signup")', description: 'Open account signup', optional: true, waitForNavigation: true, timeout: 5000 },
+      { id: 'fill_signup_email', type: 'type', target: '[data-guardian="signup-email"]', value: 'newuser@example.com', description: 'Enter signup email', timeout: 5000 },
+      { id: 'fill_signup_password', type: 'type', target: '[data-guardian="signup-password"]', value: 'P@ssword123', description: 'Enter signup password', timeout: 5000 },
+      { id: 'submit_signup_account', type: 'click', target: '[data-guardian="signup-account-submit"], button:has-text("Sign up")', description: 'Submit account signup', timeout: 5000 },
+      { id: 'wait_signup_success', type: 'waitFor', target: '[data-guardian="signup-account-success"]', description: 'Wait for signup success', timeout: 7000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="signup-account-success"]', description: 'Account signup success visible' }
+    ],
+    validators: [
+      { type: 'elementVisible', selector: '[data-guardian="signup-account-success"]' },
+      { type: 'pageContainsAnyText', textList: ['Account created', 'created', 'welcome aboard'] },
+      { type: 'elementNotVisible', selector: '[data-guardian="signup-account-error"], .error, [role="alert"]' }
+    ]
+  },
+
+  login: {
+    id: 'login',
+    name: 'Account Login',
+    goal: 'User logs in successfully (single session)',
+    riskCategory: 'TRUST/UX',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      { id: 'open_login_page', type: 'click', target: 'a[data-guardian="account-login-link"], a:has-text("Login"), a[href*="login"]', description: 'Open login page', optional: true, waitForNavigation: true, timeout: 5000 },
+      { id: 'fill_login_email', type: 'type', target: '[data-guardian="login-email"]', value: 'user@example.com', description: 'Enter login email', timeout: 5000 },
+      { id: 'fill_login_password', type: 'type', target: '[data-guardian="login-password"]', value: 'password123', description: 'Enter login password', timeout: 5000 },
+      { id: 'submit_login', type: 'click', target: '[data-guardian="login-submit"], button:has-text("Login")', description: 'Submit login', timeout: 5000 },
+      { id: 'wait_login_success', type: 'waitFor', target: '[data-guardian="login-success"]', description: 'Wait for login success', timeout: 7000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="login-success"]', description: 'Login success visible' }
+    ],
+    validators: [
+      { type: 'elementVisible', selector: '[data-guardian="login-success"]' },
+      { type: 'pageContainsAnyText', textList: ['logged in', 'welcome back', 'logged'] },
+      { type: 'elementNotVisible', selector: '[data-guardian="login-error"], .error, [role="alert"]' }
+    ]
+  },
+
+  checkout: {
+    id: 'checkout',
+    name: 'Checkout Review',
+    goal: 'User places order without payment',
+    riskCategory: 'REVENUE',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      { id: 'open_checkout', type: 'click', target: 'a[data-guardian="checkout-link"], a:has-text("Checkout"), a[href*="checkout"]', description: 'Open checkout page', optional: true, waitForNavigation: true, timeout: 5000 },
+      { id: 'place_order', type: 'click', target: '[data-guardian="checkout-place-order"], button:has-text("Place order"), button:has-text("Place Order")', description: 'Place order', timeout: 5000 },
+      { id: 'wait_order_success', type: 'waitFor', target: '[data-guardian="checkout-success"]', description: 'Wait for order confirmation', timeout: 7000 }
+    ],
+    successConditions: [
+      { type: 'selector', target: '[data-guardian="checkout-success"]', description: 'Checkout success visible' }
+    ],
+    validators: [
+      { type: 'elementVisible', selector: '[data-guardian="checkout-success"]' },
+      { type: 'pageContainsAnyText', textList: ['order placed', 'order confirmed', 'order confirmed'] },
+      { type: 'elementNotVisible', selector: '[data-guardian="checkout-error"], .error, [role="alert"]' }
+    ]
+  },
+
+  // Universal Reality Pack: deterministic, zero-config safety checks
+  universal_reality: {
+    id: 'universal_reality',
+    name: 'Universal Reality Pack',
+    goal: 'Basic site usability and safety checks',
+    riskCategory: 'TRUST/UX',
+    baseSteps: [
+      { id: 'navigate_home', type: 'navigate', target: '$BASEURL', description: 'Navigate to home page' },
+      { id: 'wait_for_body', type: 'waitFor', target: 'body', description: 'Ensure page body is visible', timeout: 5000 },
+      // Safe navigation probe (optional)
+      {
+        id: 'probe_safe_nav',
+        type: 'click',
+        target: 'nav a[href], header a[href], a[href]:not([href^="mailto:"]):not([href^="tel:"]):not([href^="javascript:"])',
+        description: 'Click a safe visible link',
+        optional: true,
+        waitForNavigation: true
+      }
+    ],
+    successConditions: [
+      // Consider success if body is visible (page loaded) or URL still valid
+      { type: 'selector', target: 'body', description: 'Page loaded and visible' }
+    ],
+    // Deterministic validators for soft issues
+    validators: [
+      // Minimal content heuristics
+      { type: 'elementVisible', selector: 'nav, header' },
+      { type: 'pageContainsAnyText', textList: ['home', 'about', 'contact', 'privacy', 'terms'] },
+      // Console errors as soft failures (WARN/FAIL recorded, outcome unchanged)
+      { type: 'noConsoleErrorsAbove', minSeverity: 'error' }
+    ]
+  }
+};
+
+function getAttemptDefinition(id) {
+  return attemptDefinitions[id] || null;
+}
+
+function getDefaultAttemptIds() {
+  return DEFAULT_ATTEMPTS.slice();
+}
+
+function listAttemptDefinitions() {
+  return Object.values(attemptDefinitions);
+}
+
+/**
+ * Phase 2: Dynamically register an auto-generated attempt
+ * @param {Object} attemptDef - Attempt definition with id, name, baseSteps, validators
+ */
+function registerAttempt(attemptDef) {
+  if (!attemptDef || !attemptDef.id) {
+    throw new Error('Cannot register attempt: missing id');
+  }
+  if (attemptDefinitions[attemptDef.id]) {
+    console.warn(`⚠️  Attempt ${attemptDef.id} already registered, skipping`);
+    return;
+  }
+  attemptDefinitions[attemptDef.id] = attemptDef;
+}
+
+module.exports = {
+  getAttemptDefinition,
+  getDefaultAttemptIds,
+  listAttemptDefinitions,
+  registerAttempt
+};