@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/browser.js

@@ -5,8 +5,15 @@ class GuardianBrowser {
     this.browser = null;
     this.context = null;
     this.page = null;
+    this.ownsContext = false; // Track if we own the context for cleanup
   }
 
+  /**
+   * Launch browser with its own context (legacy mode)
+   * @param {number} timeout - Default timeout
+   * @param {Object} options - Launch options
+   * @returns {Promise<boolean>}
+   */
   async launch(timeout = 20000, options = {}) {
     try {
       const launchOptions = { 
@@ -30,12 +37,28 @@ class GuardianBrowser {
       this.context = await this.browser.newContext(contextOptions);
       this.page = await this.context.newPage();
       this.page.setDefaultTimeout(timeout);
+      this.ownsContext = true; // We own browser and context
       return true;
     } catch (err) {
       throw new Error(`Failed to launch browser: ${err.message}`);
     }
   }
 
+  /**
+   * Phase 7.3: Use an existing context from browser pool
+   * @param {BrowserContext} context - Playwright browser context
+   * @param {Page} page - Playwright page
+   * @param {number} timeout - Default timeout
+   */
+  useContext(context, page, timeout = 20000) {
+    this.context = context;
+    this.page = page;
+    this.ownsContext = false; // Pool owns the context
+    if (timeout) {
+      this.page.setDefaultTimeout(timeout);
+    }
+  }
+
   async navigate(url, timeout = 20000) {
     try {
       const response = await this.page.goto(url, {
@@ -82,7 +105,11 @@ class GuardianBrowser {
 
   async close() {
     try {
-      if (this.browser) await this.browser.close();
+      // Phase 7.3: Only close browser if we own it (legacy mode)
+      // If using pool context, pool handles cleanup
+      if (this.ownsContext && this.browser) {
+        await this.browser.close();
+      }
     } catch (err) {
       // Ignore close errors
     }

package/src/guardian/ci-cli.js

@@ -0,0 +1,121 @@
+const path = require('path');
+const fs = require('fs');
+const { scanJourney } = require('./journey-scanner');
+const { detectSiteIntent, selectJourneyByIntent } = require('./intent-detector');
+const { buildBaselineFromJourneyResult, compareAgainstBaseline, classifySeverity } = require('./drift-detector');
+const { shouldEmitAlert } = require('./alert-ledger');
+
+/**
+ * Run CI gate scan:
+ * - Single journey run
+ * - Compare against baseline if exists
+ * - Apply alert dedup + cooldown
+ * - Generate ci-result.json
+ * - Exit with stable codes
+ */
+async function runCIGate(config) {
+  const { baseUrl, artifactsDir, headless, timeout, preset, presetProvided } = config;
+  
+  const outDir = path.resolve(artifactsDir, 'ci');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  console.log(`[CI] Scanning ${baseUrl}...`);
+
+  let selectedPreset = preset;
+  let siteIntent = null;
+
+  // Auto-detect intent if no preset provided
+  if (!presetProvided) {
+    console.log('[CI] Auto-detecting site intent...');
+    try {
+      siteIntent = await detectSiteIntent(baseUrl, { headless, timeout });
+      selectedPreset = selectJourneyByIntent(siteIntent);
+      console.log(`[CI] Detected intent: ${siteIntent.type}, selected preset: ${selectedPreset}`);
+    } catch (err) {
+      console.error('[CI] Intent detection failed:', err.message);
+      selectedPreset = 'saas';
+    }
+  }
+
+  // Run journey
+  let result;
+  try {
+    result = await scanJourney({ baseUrl, preset: selectedPreset, headless, timeout });
+  } catch (err) {
+    console.error('[CI] Journey scan failed:', err.message);
+    const ciResult = {
+      decision: 'DO_NOT_LAUNCH',
+      severity: 'CRITICAL',
+      driftDetected: false,
+      goalReached: false,
+      intent: siteIntent ? siteIntent.type : 'unknown',
+      reasons: ['Journey scan failed: ' + err.message],
+      timestamp: new Date().toISOString()
+    };
+    fs.writeFileSync(path.join(outDir, 'ci-result.json'), JSON.stringify(ciResult, null, 2));
+    return 2;
+  }
+
+  // Check for baseline
+  const baselinePath = path.resolve(artifactsDir, 'baseline.json');
+  let driftInfo = null;
+  let severity = 'WARN';
+
+  if (fs.existsSync(baselinePath)) {
+    console.log('[CI] Comparing against baseline...');
+    const baselineData = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    driftInfo = compareAgainstBaseline(result, baselineData);
+    
+    if (driftInfo.hasDrift) {
+      severity = classifySeverity(driftInfo, result);
+      console.log(`[CI] Drift detected (${severity}): ${driftInfo.reasons.join(', ')}`);
+      
+      // Check alert dedup and cooldown
+      const alertDecision = shouldEmitAlert(driftInfo.reasons, severity, artifactsDir);
+      if (!alertDecision.emit) {
+        console.log(`[CI] Alert suppressed: ${alertDecision.reason}`);
+        // Generate CI result showing suppression
+        const ciResult = {
+          decision: result.decision,
+          severity,
+          driftDetected: true,
+          goalReached: result.goalReached || false,
+          intent: result.intent || 'unknown',
+          reasons: driftInfo.reasons,
+          alertSuppressed: true,
+          suppressionReason: alertDecision.reason,
+          timestamp: new Date().toISOString()
+        };
+        fs.writeFileSync(path.join(outDir, 'ci-result.json'), JSON.stringify(ciResult, null, 2));
+        return severity === 'CRITICAL' ? 4 : 0;
+      }
+    } else {
+      console.log('[CI] No drift detected');
+    }
+  } else {
+    console.log('[CI] No baseline found, capturing new baseline...');
+    const baseline = buildBaselineFromJourneyResult(result);
+    fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2));
+  }
+
+  // Generate ci-result.json
+  const ciResult = {
+    decision: result.decision,
+    severity: driftInfo ? severity : (result.decision === 'DO_NOT_LAUNCH' ? 'CRITICAL' : 'WARN'),
+    driftDetected: driftInfo ? driftInfo.hasDrift : false,
+    goalReached: result.goalReached || false,
+    intent: result.intent || 'unknown',
+    reasons: driftInfo ? driftInfo.reasons : [],
+    timestamp: new Date().toISOString()
+  };
+
+  fs.writeFileSync(path.join(outDir, 'ci-result.json'), JSON.stringify(ciResult, null, 2));
+  console.log(`[CI] Result: ${ciResult.decision} (${ciResult.severity})`);
+
+  // Exit code based on decision and severity
+  if (ciResult.decision === 'DO_NOT_LAUNCH') return 2;
+  if (ciResult.decision === 'RISK' || ciResult.severity === 'WARN') return 1;
+  return 0;
+}
+
+module.exports = { runCIGate };

package/src/guardian/ci-mode.js

@@ -0,0 +1,15 @@
+function isCiMode() {
+  const ci = process.env.CI;
+  const gha = process.env.GITHUB_ACTIONS;
+  const guardianCi = process.env.GUARDIAN_CI;
+
+  const normalize = (value) => String(value || '').toLowerCase();
+  const isTrueish = (value) => {
+    const v = normalize(value);
+    return v === 'true' || v === '1' || v === 'yes' || v === 'on';
+  };
+
+  return isTrueish(ci) || isTrueish(gha) || isTrueish(guardianCi);
+}
+
+module.exports = { isCiMode };

package/src/guardian/ci-output.js

@@ -0,0 +1,38 @@
+const { formatRunSummary, deriveBaselineVerdict } = require('./run-summary');
+const MAX_REASONS_DEFAULT = 3;
+
+function pickReason(flow) {
+  if (Array.isArray(flow.failureReasons) && flow.failureReasons.length > 0) {
+    return flow.failureReasons[0];
+  }
+  if (flow.error) return flow.error;
+  if (flow.successEval && Array.isArray(flow.successEval.reasons) && flow.successEval.reasons.length > 0) {
+    return flow.successEval.reasons[0];
+  }
+  return 'no reason captured';
+}
+
+function formatCiSummary({ flowResults = [], diffResult = null, baselineCreated = false, exitCode = 0, maxReasons = MAX_REASONS_DEFAULT }) {
+  const lines = [];
+  lines.push('CI MODE: ON');
+  lines.push(formatRunSummary({ flowResults, diffResult, baselineCreated, exitCode }, { label: 'Summary' }));
+
+  const verdict = exitCode === 0 ? 'OBSERVED' : exitCode === 1 ? 'PARTIAL' : 'INSUFFICIENT_DATA';
+  lines.push(`Result: ${verdict}`);
+
+  if (exitCode !== 0) {
+    lines.push('Observed issues:');
+    const troubled = flowResults.filter(f => f.outcome === 'FAILURE' || f.outcome === 'FRICTION');
+    troubled.slice(0, maxReasons).forEach(flow => {
+      const reason = pickReason(flow);
+      lines.push(` - ${flow.flowName || flow.flowId || 'flow'}: ${flow.outcome} | ${reason}`);
+    });
+    if (troubled.length > maxReasons) {
+      lines.push(` - … ${troubled.length - maxReasons} more issues`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { formatCiSummary, deriveBaselineVerdict };

package/src/guardian/cli-summary.js

@@ -1,82 +1,115 @@
 /**
- * CLI Summary Module
- * 
- * Generate human-friendly CLI summaries at the end of Guardian runs.
- * Shows critical info, top risks, and actionable next steps.
- */
-
-/**
- * Generate final CLI summary
- * @param {object} snapshot - Guardian snapshot
- * @param {object} policyEval - Policy evaluation result
- * @returns {string} Formatted CLI summary
- */
-function generateCliSummary(snapshot, policyEval) {
-  if (!snapshot) {
-    return 'No snapshot data available.';
-  }
-
+// STRICT CLI SUMMARY: factual, artifact-traceable lines only
+function generateCliSummary(snapshot, policyEval, baselineCheckResult, options = {}) {
+  if (!snapshot) return 'No snapshot data available.';
   const meta = snapshot.meta || {};
-  const marketImpact = snapshot.marketImpactSummary || {};
-  const counts = marketImpact.countsBySeverity || { CRITICAL: 0, WARNING: 0, INFO: 0 };
-  const topRisks = marketImpact.topRisks || [];
-  const attempts = snapshot.attempts || [];
-  const discovery = snapshot.discovery || {};
+  const coverage = snapshot.coverage || {};
+  const counts = coverage.counts || {};
+  const evidence = snapshot.evidenceMetrics || {};
+  const resolved = snapshot.resolved || {};
 
   let output = '\n';
   output += '━'.repeat(70) + '\n';
   output += '🛡️  Guardian Reality Summary\n';
   output += '━'.repeat(70) + '\n\n';
 
-  // Target URL
   output += `Target: ${meta.url || 'unknown'}\n`;
   output += `Run ID: ${meta.runId || 'unknown'}\n\n`;
 
-  // Risk Counts
-  output += '📊 Risk Summary:\n';
-  output += `  🚨 CRITICAL: ${counts.CRITICAL}`;
-  if (counts.CRITICAL > 0) output += ' (Revenue impact)';
-  output += '\n';
-  output += `  ⚠️  WARNING:  ${counts.WARNING}`;
-  if (counts.WARNING > 0) output += ' (User experience)';
-  output += '\n';
-  output += `  ℹ️  INFO:     ${counts.INFO}`;
-  if (counts.INFO > 0) output += ' (Minor issues)';
-  output += '\n\n';
-
-  // Top Risks (up to 3)
-  if (topRisks.length > 0) {
-    // Preserve legacy label for backward compatibility
-    output += '🔥 Top Risk:\n';
-    // New: compact list of top 3 issues
-    output += '   (Top Issues)\n';
-    topRisks.slice(0, 3).forEach((risk, idx) => {
-      output += `   ${idx + 1}. ${risk.humanReadableReason || 'Unknown issue'}\n`;
-      output += `      Impact: ${risk.impactScore || 0} (${risk.category || 'UNKNOWN'}) | Severity: ${risk.severity || 'INFO'}\n`;
-    });
-
-    // Link evidence if available for the top-most
-    const topRisk = topRisks[0];
-    const relatedAttempt = attempts.find(a => 
-      a.attemptId === topRisk.attemptId || 
-      (topRisk.humanReadableReason || '').toLowerCase().includes(a.attemptName?.toLowerCase() || '')
-    );
-    if (relatedAttempt && relatedAttempt.evidence) {
-      output += `   Evidence: ${relatedAttempt.evidence.screenshotPath || 'See report'}\n`;
+  const pe = snapshot.policyEvaluation || {};
+  output += `Policy Verdict: ${meta.result || (pe.passed ? 'PASSED' : pe.exitCode === 2 ? 'WARN' : 'FAILED')}\n`;
+  output += `Exit Code: ${pe.exitCode ?? 'unknown'}\n`;
+
+  const planned = coverage.total ?? (resolved.coverage?.total) ?? 'unknown';
+  const executed = counts.executedCount ?? (resolved.coverage?.executedCount) ?? coverage.executed ?? 'unknown';
+  output += `Executed / Planned: ${executed} / ${planned}\n`;
+
+  const completeness = evidence.completeness ?? resolved.evidenceMetrics?.completeness ?? 'unknown';
+  const integrity = evidence.integrity ?? resolved.evidenceMetrics?.integrity ?? 'unknown';
+  output += `Coverage Completeness: ${typeof completeness === 'number' ? completeness.toFixed(4) : completeness}\n`;
+  output += `Evidence Integrity: ${typeof integrity === 'number' ? integrity.toFixed(4) : integrity}\n`;
+
+  if (meta.attestation?.hash) {
+    output += `Attestation: ${meta.attestation.hash}\n`;
+  // STRICT CLI SUMMARY: factual, artifact-traceable lines only
+  function generateCliSummary(snapshot, policyEval, baselineCheckResult, options = {}) {
+    if (!snapshot) return 'No snapshot data available.';
+    const meta = snapshot.meta || {};
+    const coverage = snapshot.coverage || {};
+    const counts = coverage.counts || {};
+    const evidence = snapshot.evidenceMetrics || {};
+    const resolved = snapshot.resolved || {};
+
+    let output = '\n';
+    output += '━'.repeat(70) + '\n';
+    output += '🛡️  Guardian Reality Summary\n';
+    output += '━'.repeat(70) + '\n\n';
+
+    output += `Target: ${meta.url || 'unknown'}\n`;
+    output += `Run ID: ${meta.runId || 'unknown'}\n\n`;
+
+    const pe = snapshot.policyEvaluation || {};
+    output += `Policy Verdict: ${meta.result || (pe.passed ? 'PASSED' : pe.exitCode === 2 ? 'WARN' : 'FAILED')}\n`;
+    output += `Exit Code: ${pe.exitCode ?? 'unknown'}\n`;
+
+    const planned = coverage.total ?? (resolved.coverage?.total) ?? 'unknown';
+    const executed = counts.executedCount ?? (resolved.coverage?.executedCount) ?? coverage.executed ?? 'unknown';
+    output += `Executed / Planned: ${executed} / ${planned}\n`;
+
+    const completeness = evidence.completeness ?? resolved.evidenceMetrics?.completeness ?? 'unknown';
+    const integrity = evidence.integrity ?? resolved.evidenceMetrics?.integrity ?? 'unknown';
+    output += `Coverage Completeness: ${typeof completeness === 'number' ? completeness.toFixed(4) : completeness}\n`;
+    output += `Evidence Integrity: ${typeof integrity === 'number' ? integrity.toFixed(4) : integrity}\n`;
+
+    if (meta.attestation?.hash) {
+      output += `Attestation: ${meta.attestation.hash}\n`;
     }
-    output += '\n';
-  }
 
-  // Attempt Summary
-  const successfulAttempts = attempts.filter(a => a.outcome === 'SUCCESS').length;
-  const totalAttempts = attempts.length;
-  if (totalAttempts > 0) {
-    output += '🎯 Attempts:\n';
-    output += `   ${successfulAttempts}/${totalAttempts} successful`;
-    if (successfulAttempts < totalAttempts) {
-      output += ` (${totalAttempts - successfulAttempts} failed)`;
+    // Audit Summary
+    const executedAttempts = (snapshot.attempts || []).filter(a => a.executed).map(a => a.attemptId);
+    output += '\nAudit Summary:\n';
+    output += `  Tested (${executedAttempts.length}): ${executedAttempts.join(', ') || 'none'}\n`;
+    const skippedDisabled = (coverage.skippedDisabledByPreset || []).map(s => s.attempt);
+    const skippedUserFiltered = (coverage.skippedUserFiltered || []).map(s => s.attempt);
+    const skippedNotApplicable = (coverage.skippedNotApplicable || []).map(s => s.attempt);
+    const skippedMissing = (coverage.skippedMissing || []).map(s => s.attempt);
+    output += `  Not Tested — DisabledByPreset (${skippedDisabled.length}): ${skippedDisabled.join(', ') || 'none'}\n`;
+    output += `  Not Tested — UserFiltered (${skippedUserFiltered.length}): ${skippedUserFiltered.join(', ') || 'none'}\n`;
+    output += `  Not Tested — NotApplicable (${skippedNotApplicable.length}): ${skippedNotApplicable.join(', ') || 'none'}\n`;
+    output += `  Not Tested — Missing (${skippedMissing.length}): ${skippedMissing.join(', ') || 'none'}\n`;
+
+    const reasons = Array.isArray(pe.reasons) ? pe.reasons : [];
+    if (reasons.length > 0) {
+      output += '\nPolicy Reasons:\n';
+      reasons.forEach(r => {
+        if (typeof r === 'string') output += `  • ${r}\n`; else if (r.message) output += `  • ${r.message}\n`; else output += `  • ${JSON.stringify(r)}\n`;
+      });
     }
-    output += '\n\n';
+
+    output += '\n📁 Full report: ' + (meta.runId ? `artifacts/${meta.runId}/` : 'See artifacts/') + '\n\n';
+    output += '━'.repeat(70) + '\n';
+    return output;
+  }
+        if (!primary) return null;
+        try { const p = new URL(primary.url); return `request: ${primary.method} ${p.pathname} → ${primary.status}`; }
+        catch { return `request: ${primary.method} ${primary.url} → ${primary.status}`; }
+      })();
+      const navLine = ev.urlChanged ? (() => {
+        try { const from = new URL(snapshot.meta.url).pathname; const to = ''; return `navigation: changed`; }
+        catch { return `navigation: changed`; }
+      })() : null;
+      const formStates = [];
+      if (ev.formCleared) formStates.push('cleared');
+      if (ev.formDisabled) formStates.push('disabled');
+      if (ev.formDisappeared) formStates.push('disappeared');
+      const formLine = formStates.length ? `form: ${formStates.join(', ')}` : null;
+      const evidenceLines = [reqLine, navLine, formLine].filter(Boolean);
+      if (evidenceLines.length) {
+        output += '     Evidence:\n';
+        evidenceLines.slice(0, 2).forEach(line => { output += `       - ${line}\n`; });
+      }
+    });
+    output += '\n';
   }
 
   // Discovery Summary
@@ -104,6 +137,73 @@ function generateCliSummary(snapshot, policyEval) {
     output += `   Exit code: ${policyEval.exitCode || 0}\n\n`;
   }
 
+  // Baseline Comparison (Phase 3.2)
+  if (baselineCheckResult) {
+    const verdict = baselineCheckResult.overallRegressionVerdict || 'NO_BASELINE';
+    
+    if (verdict === 'NO_BASELINE') {
+      output += '📊 Baseline Comparison: not found (no comparison)\n\n';
+    } else if (verdict === 'BASELINE_UNUSABLE') {
+      output += '📊 Baseline Comparison: unusable (skipped)\n\n';
+    } else {
+      const emoji = verdict === 'NO_REGRESSION' ? '✅' : 
+                    verdict === 'REGRESSION_FRICTION' ? '🟡' :
+                    '🔴';
+      
+      output += '📊 Baseline Comparison:\n';
+      output += `   ${emoji} ${verdict.replace(/_/g, ' ')}\n`;
+      
+      // Show per-attempt changes
+      const comparisons = baselineCheckResult.comparisons || [];
+      const regressions = comparisons.filter(c => c.regressionType !== 'NO_REGRESSION');
+      const improvements = comparisons.filter(c => c.improvements && c.improvements.length > 0);
+      
+      if (regressions.length > 0) {
+        output += '   \n';
+        output += '   Regressions detected:\n';
+        regressions.slice(0, 3).forEach(r => {
+          const label = r.attemptId || 'unknown';
+          const type = r.regressionType.replace(/_/g, ' ');
+          const reasons = r.regressionReasons.slice(0, 1).join('; ') || 'See report';
+          output += `     • ${label}: ${type}\n`;
+          output += `       ${reasons}\n`;
+        });
+        if (regressions.length > 3) {
+          output += `     ... and ${regressions.length - 3} more regressions\n`;
+        }
+      }
+      
+      if (improvements.length > 0) {
+        output += '   \n';
+        output += '   Improvements detected:\n';
+        improvements.slice(0, 3).forEach(i => {
+          const label = i.attemptId || 'unknown';
+          const improvementText = i.improvements.slice(0, 1).join('; ') || 'Improved';
+          output += `     • ${label}: ${improvementText}\n`;
+        });
+        if (improvements.length > 3) {
+          output += `     ... and ${improvements.length - 3} more improvements\n`;
+        }
+      }
+      
+      // Show per-flow changes
+      const flowComparisons = baselineCheckResult.flowComparisons || [];
+      const flowRegressions = flowComparisons.filter(c => c.regressionType !== 'NO_REGRESSION');
+      
+      if (flowRegressions.length > 0) {
+        output += '   \n';
+        output += '   Flow regressions:\n';
+        flowRegressions.forEach(f => {
+          const label = f.flowId || 'unknown';
+          const type = f.regressionType.replace(/_/g, ' ');
+          output += `     • ${label}: ${type}\n`;
+        });
+      }
+      
+      output += '\n';
+    }
+  }
+
   // Next Action
   output += '👉 Next Action:\n';
   if (counts.CRITICAL > 0) {
@@ -130,8 +230,8 @@ function generateCliSummary(snapshot, policyEval) {
 /**
  * Print summary to console
  */
-function printCliSummary(snapshot, policyEval) {
-  const summary = generateCliSummary(snapshot, policyEval);
+function printCliSummary(snapshot, policyEval, baselineCheckResult, options = {}) {
+  const summary = generateCliSummary(snapshot, policyEval, baselineCheckResult, options);
   console.log(summary);
 }
 

package/src/guardian/config-loader.js

@@ -0,0 +1,162 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  crawl: {
+    maxPages: 25,
+    maxDepth: 3,
+  },
+  timeouts: {
+    navigationMs: 20000,
+  },
+  output: {
+    dir: './.odavlguardian',
+  }
+};
+
+function findConfigFile(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(current, 'guardian.config.json');
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function validatePositiveInt(value, name, allowZero = false) {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new Error(`${name} must be a number`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`);
+  }
+  if (allowZero) {
+    if (value < 0) throw new Error(`${name} must be >= 0`);
+  } else {
+    if (value <= 0) throw new Error(`${name} must be > 0`);
+  }
+}
+
+function validateConfigShape(raw, filePath) {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`Invalid config in ${filePath}: expected an object`);
+  }
+
+  const effective = {
+    crawl: {
+      maxPages: DEFAULTS.crawl.maxPages,
+      maxDepth: DEFAULTS.crawl.maxDepth
+    },
+    timeouts: {
+      navigationMs: DEFAULTS.timeouts.navigationMs
+    },
+    output: {
+      dir: DEFAULTS.output.dir
+    }
+  };
+
+  if (raw.crawl) {
+    if (raw.crawl.maxPages !== undefined) {
+      validatePositiveInt(raw.crawl.maxPages, 'crawl.maxPages');
+      effective.crawl.maxPages = raw.crawl.maxPages;
+    }
+    if (raw.crawl.maxDepth !== undefined) {
+      validatePositiveInt(raw.crawl.maxDepth, 'crawl.maxDepth', true);
+      effective.crawl.maxDepth = raw.crawl.maxDepth;
+    }
+  }
+
+  if (raw.timeouts) {
+    if (raw.timeouts.navigationMs !== undefined) {
+      validatePositiveInt(raw.timeouts.navigationMs, 'timeouts.navigationMs');
+      effective.timeouts.navigationMs = raw.timeouts.navigationMs;
+    }
+  }
+
+  if (raw.output) {
+    if (raw.output.dir !== undefined) {
+      if (typeof raw.output.dir !== 'string' || raw.output.dir.trim() === '') {
+        throw new Error('output.dir must be a non-empty string');
+      }
+      effective.output.dir = raw.output.dir;
+    }
+  }
+
+  return effective;
+}
+
+function applyLocalConfig(inputConfig) {
+  const cliSource = inputConfig._cliSource || {};
+  const discoveredPath = findConfigFile();
+  let fileConfig = null;
+  let fileEffective = null;
+
+  if (discoveredPath) {
+    try {
+      fileConfig = JSON.parse(fs.readFileSync(discoveredPath, 'utf8'));
+      fileEffective = validateConfigShape(fileConfig, discoveredPath);
+    } catch (err) {
+      throw new Error(`Invalid guardian.config.json at ${discoveredPath}: ${err.message}`);
+    }
+  }
+
+  const effective = {
+    crawl: { ...DEFAULTS.crawl },
+    timeouts: { ...DEFAULTS.timeouts },
+    output: { ...DEFAULTS.output }
+  };
+
+  if (fileEffective) {
+    effective.crawl = { ...effective.crawl, ...fileEffective.crawl };
+    effective.timeouts = { ...effective.timeouts, ...fileEffective.timeouts };
+    effective.output = { ...effective.output, ...fileEffective.output };
+  }
+
+  // CLI overrides
+  if (inputConfig.maxPages !== undefined) {
+    validatePositiveInt(inputConfig.maxPages, 'crawl.maxPages');
+    effective.crawl.maxPages = inputConfig.maxPages;
+  }
+  if (inputConfig.maxDepth !== undefined) {
+    validatePositiveInt(inputConfig.maxDepth, 'crawl.maxDepth', true);
+    effective.crawl.maxDepth = inputConfig.maxDepth;
+  }
+  if (inputConfig.timeout !== undefined) {
+    validatePositiveInt(inputConfig.timeout, 'timeouts.navigationMs');
+    effective.timeouts.navigationMs = inputConfig.timeout;
+  }
+  if (inputConfig.artifactsDir !== undefined) {
+    if (typeof inputConfig.artifactsDir !== 'string' || inputConfig.artifactsDir.trim() === '') {
+      throw new Error('output.dir must be a non-empty string');
+    }
+    effective.output.dir = inputConfig.artifactsDir;
+  }
+
+  // Determine source label
+  let source = 'defaults';
+  if (fileEffective) source = 'guardian.config.json';
+  const cliOverride = cliSource.maxPages || cliSource.maxDepth || cliSource.timeout || cliSource.artifactsDir;
+  if (cliOverride) source = 'cli';
+
+  const finalConfig = { ...inputConfig };
+  finalConfig.maxPages = effective.crawl.maxPages;
+  finalConfig.maxDepth = effective.crawl.maxDepth;
+  finalConfig.timeout = effective.timeouts.navigationMs;
+  finalConfig.artifactsDir = effective.output.dir;
+
+  return {
+    config: finalConfig,
+    report: {
+      source,
+      path: fileEffective ? path.resolve(discoveredPath) : null,
+      effective
+    }
+  };
+}
+
+module.exports = { applyLocalConfig, DEFAULTS };