pqcheck 0.16.24 → 0.16.29

package/README.md

@@ -8,7 +8,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![license](https://img.shields.io/npm/l/pqcheck.svg?style=flat-square&color=06b6d4)](./LICENSE)
 
-> **Latest: v0.16.24** — **Route Assertions (R87).** Closes the gap that left Cipherwake silent on backend/admin-heavy deploys. Declare your private routes in `.cipherwake.json` and Cipherwake asserts they're still gated on every deploy. Any critical failure (declared `protected`, actually `exposed`) blocks the deploy unconditionally — the catastrophic "/admin became public" case. Three sources merge: customer config + nearly-universal defaults + auto-detected from `robots.txt` and homepage. New `/methodology/route-assertions` documents the feature; `/methodology/why-not-authenticated-crawling` explains the design decision to never hold customer credentials. [Full changelog →](./CHANGELOG.md)
+> **Latest: v0.16.29** — Fixed a high-volume false positive caught by external testing: WAF-mitigated 403s on `/wp-admin` (and any `expect: missing` default) were firing as "WordPress leak" on every Vercel/Cloudflare-hosted non-WP app. The probe now detects `x-vercel-mitigated` / `cf-mitigated` headers and classifies them as `blocked` (not `protected`). And `expect: missing` now semantically means "not reachable to anonymous users" — 404/401/403/3xx/WAF-block all satisfy; only 200-serving-content fails. Every catastrophic catch (`.env` leak at 200, real WP at 200, public `/api/admin`) preserved. Verified with 23 new tests covering all classification × expectation combinations. [Full changelog →](./CHANGELOG.md)
 
 ## Two ways to use it
 

package/bin/pqcheck.js

@@ -188,6 +188,17 @@ async function main() {
   if (args[0] === "init") {
     return runInitCommand(args.slice(1));
   }
+  // R89.LOCAL — local-only stats commands. Read/write .cipherwake/stats.json
+  // in the repo root. ZERO network requests. Privacy-by-design.
+  if (args[0] === "stats") {
+    return runStatsCommand(args.slice(1));
+  }
+  if (args[0] === "dismiss") {
+    return runDismissCommand(args.slice(1));
+  }
+  if (args[0] === "confirm") {
+    return runConfirmCommand(args.slice(1));
+  }
   if (args[0] === "deploy-check") {
     return runDeployCheckCommand(args.slice(1));
   }
@@ -991,6 +1002,18 @@ async function readRouteAssertionsConfig() {
             _warnConfigIssue(`duplicate path "${normPath}" in assertions — second occurrence ignored.`);
             continue;
           }
+          // R87.6 — validate bodyContains / bodyAbsent if present.
+          if (a.bodyContains !== undefined && typeof a.bodyContains !== "string" && !(Array.isArray(a.bodyContains) && a.bodyContains.every((s) => typeof s === "string"))) {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has invalid "bodyContains" — must be a string or array of strings. Body check disabled for this assertion.`);
+            delete a.bodyContains;
+          }
+          if (a.bodyAbsent !== undefined && typeof a.bodyAbsent !== "string" && !(Array.isArray(a.bodyAbsent) && a.bodyAbsent.every((s) => typeof s === "string"))) {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has invalid "bodyAbsent" — must be a string or array of strings. Body check disabled for this assertion.`);
+            delete a.bodyAbsent;
+          }
+          if ((a.bodyContains !== undefined || a.bodyAbsent !== undefined) && a.expect !== "protected") {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has body assertions but expect=${JSON.stringify(a.expect)}. Body checks only run on expect=protected.`);
+          }
           seen.add(normPath);
           cleaned.push({ ...a, path: normPath });
         }
@@ -1016,10 +1039,49 @@ async function readRouteAssertionsConfig() {
 // the deploy unconditionally — this is the catastrophic "admin became
 // public" case the feature exists to catch. High/medium failures promote
 // to `review`.
+// R89.G (2026-06-05) — narrative line for every scan. The reason "drift-only"
+// feels not-worth-paying-for is the silent-on-pass UX. A one-liner narrative
+// on every scan ("Public surface since last deploy: 0 routes changed, 0
+// headers regressed, deploy healthy") makes the gate FEEL alive even when
+// it's green. The AI coder reads this in the response and can surface it
+// to the user in plain English.
+function buildTrustDiffNarrative({ deltaCount, assertionsFailedCount, assertionsCriticalCount, deployStatus, secretsCriticalCount, secretsFindingsTotal, cookieFailedCount, headerFailedCount, posture }) {
+  const bits = [];
+  // Lead with the catastrophic items first
+  if (secretsCriticalCount > 0) bits.push(`${secretsCriticalCount} leaked secret${secretsCriticalCount === 1 ? "" : "s"} in JS bundle`);
+  if (deployStatus && deployStatus !== "healthy" && deployStatus !== "unreachable") {
+    bits.push(`deploy ${deployStatus.replace(/_/g, " ")}`);
+  }
+  if (assertionsCriticalCount > 0) bits.push(`${assertionsCriticalCount} declared route${assertionsCriticalCount === 1 ? "" : "s"} regressed`);
+  if (cookieFailedCount > 0) bits.push(`${cookieFailedCount} cookie flag${cookieFailedCount === 1 ? "" : "s"} weakened`);
+  if (headerFailedCount > 0) bits.push(`${headerFailedCount} required header${headerFailedCount === 1 ? "" : "s"} missing`);
+  if (deltaCount > 0) bits.push(`${deltaCount} trust-surface change${deltaCount === 1 ? "" : "s"} since baseline`);
+  if (assertionsFailedCount > 0 && assertionsCriticalCount === 0) bits.push(`${assertionsFailedCount} route assertion${assertionsFailedCount === 1 ? "" : "s"} for review`);
+  if (secretsFindingsTotal > secretsCriticalCount) bits.push(`${secretsFindingsTotal - secretsCriticalCount} non-critical secret finding${(secretsFindingsTotal - secretsCriticalCount) === 1 ? "" : "s"}`);
+  if (bits.length === 0) {
+    return `Public surface since last deploy: no drift, all declared invariants pass${deployStatus === "healthy" ? ", deploy healthy" : ""}${posture ? `, posture ${posture}` : ""}.`;
+  }
+  return `Public surface since last deploy: ${bits.join("; ")}${deployStatus === "healthy" ? " (homepage healthy)" : ""}.`;
+}
+
 function shipDecisionFromAssertions(summary) {
   if (!summary) return null;
-  if (summary.criticalFailures && summary.criticalFailures.length > 0) return "block";
-  if (summary.failed > 0) return "review";
+  // R89/R88 wave 2 + R90 — fold in deploy health + secrets + cookies + headers + TLS.
+  // Critical case auto-blocks; any non-critical failure promotes to review.
+  const deployBroken = summary.deployHealth && summary.deployHealth.status !== "healthy" && summary.deployHealth.status !== "unreachable";
+  const secretsLeaked = summary.secrets && summary.secrets.criticalCount > 0;
+  const cookieCritical = (summary.cookieCriticalFailures || 0) > 0;
+  const tlsCritical = summary.tlsExpiry && !summary.tlsExpiry.passed && summary.tlsExpiry.severity === "critical";
+  if ((summary.criticalFailures && summary.criticalFailures.length > 0) ||
+      (summary.headerCriticalFailures && summary.headerCriticalFailures.length > 0) ||
+      deployBroken || secretsLeaked || cookieCritical || tlsCritical) {
+    return "block";
+  }
+  const headerFailed = (summary.headerResults || []).filter((r) => !r.passed).length;
+  const cookieFailed = (summary.cookieResults || []).filter((r) => !r.passed).length;
+  const secretsFound = summary.secrets && summary.secrets.findings && summary.secrets.findings.length > 0;
+  const tlsFailed = summary.tlsExpiry && !summary.tlsExpiry.passed;
+  if (summary.failed > 0 || headerFailed > 0 || cookieFailed > 0 || secretsFound || tlsFailed) return "review";
   return "pass";
 }
 
@@ -1037,12 +1099,85 @@ function formatRouteAssertionsBlock(summary) {
   lines.push(`sources_default=${summary.sources.default}`);
   lines.push(`sources_auto=${summary.sources.auto}`);
   lines.push(`sources_auto_suppressed=${summary.sources.autoSuppressed || 0}`);
+  lines.push(`sources_dismissed=${summary.sources.dismissed || 0}`);
+  // R88 — header invariants block alongside route assertions
+  if (Array.isArray(summary.headerResults) && summary.headerResults.length > 0) {
+    lines.push("--- HEADER INVARIANTS ---");
+    lines.push(`header_total=${summary.headerResults.length}`);
+    lines.push(`header_passed=${summary.headerResults.filter((r) => r.passed).length}`);
+    lines.push(`header_failed=${summary.headerResults.filter((r) => !r.passed).length}`);
+    lines.push(`header_critical_failures=${(summary.headerCriticalFailures || []).length}`);
+    for (const h of summary.headerResults) {
+      const status = h.passed ? "PASS" : "FAIL";
+      const sev = h.passed ? "info" : h.severity;
+      const wantVal = h.expectedValue ? `="${h.expectedValue}"` : "";
+      const gotVal = h.actualValue !== null && h.actualValue !== undefined ? `, got "${String(h.actualValue).slice(0, 80)}"` : ", got <absent>";
+      const why = h.why ? ` — ${h.why}` : "";
+      lines.push(`${status} [${sev}] header:${h.header} expect=${h.expect}${wantVal}${gotVal}${why}`);
+    }
+  }
+  // R89 — deploy-health check
+  if (summary.deployHealth) {
+    const dh = summary.deployHealth;
+    lines.push("--- DEPLOY HEALTH ---");
+    lines.push(`deploy_status=${dh.status}`);
+    lines.push(`deploy_http_status=${dh.httpStatus === null ? "?" : dh.httpStatus}`);
+    lines.push(`deploy_body_bytes=${dh.bodyBytes}`);
+    if (dh.matchedErrorMarker) lines.push(`deploy_matched_error_marker=${dh.matchedErrorMarker}`);
+    if (dh.missingLandmark) lines.push(`deploy_missing_landmark=${dh.missingLandmark}`);
+    if (dh.errorReason) lines.push(`deploy_error_reason=${dh.errorReason}`);
+    lines.push(`deploy_summary=${dh.summary}`);
+  }
+  // R88 wave 2 — secret scanner
+  if (summary.secrets) {
+    const s = summary.secrets;
+    lines.push("--- SECRET SCAN ---");
+    lines.push(`secrets_scanned=${s.scanned}`);
+    lines.push(`secrets_bundles_fetched=${s.bundlesFetched}`);
+    lines.push(`secrets_findings_total=${s.findings.length}`);
+    lines.push(`secrets_critical_count=${s.criticalCount}`);
+    for (const f of s.findings) {
+      lines.push(`FAIL [${f.severity}] secret:${f.patternId} source=${f.source} redacted=${f.redactedSample} — ${f.name}`);
+    }
+  }
+  // R90 — TLS cert expiry invariant
+  if (summary.tlsExpiry) {
+    const t = summary.tlsExpiry;
+    lines.push("--- TLS EXPIRY ---");
+    lines.push(`tls_checked=${t.checked}`);
+    lines.push(`tls_days_remaining=${t.daysRemaining === null ? "?" : t.daysRemaining}`);
+    lines.push(`tls_min_required=${t.minRequired}`);
+    lines.push(`tls_passed=${t.passed}`);
+    lines.push(`tls_summary=${t.summary}`);
+  }
+  // R88 wave 2 — cookie invariants
+  if (Array.isArray(summary.cookieResults) && summary.cookieResults.length > 0) {
+    lines.push("--- COOKIE INVARIANTS ---");
+    lines.push(`cookie_total=${summary.cookieResults.length}`);
+    lines.push(`cookie_passed=${summary.cookieResults.filter((r) => r.passed).length}`);
+    lines.push(`cookie_failed=${summary.cookieResults.filter((r) => !r.passed).length}`);
+    lines.push(`cookie_critical_failures=${summary.cookieCriticalFailures || 0}`);
+    for (const c of summary.cookieResults) {
+      const status = c.passed ? "PASS" : "FAIL";
+      const sev = c.passed ? "info" : c.severity;
+      const matched = c.matchedCookies.length > 0 ? c.matchedCookies.join(",") : "<no matching cookies>";
+      const why = c.why ? ` — ${c.why}` : "";
+      if (c.failures.length === 0) {
+        lines.push(`${status} [${sev}] cookie:${c.namePattern} matched=${matched}${why}`);
+      } else {
+        for (const f of c.failures) {
+          lines.push(`FAIL [${sev}] cookie:${c.namePattern} cookie=${f.cookieName} reason=${f.reason}${why}`);
+        }
+      }
+    }
+  }
   for (const r of summary.results) {
     const status = r.passed ? "PASS" : "FAIL";
     const sev = r.passed ? "info" : r.severity;
     const why = r.why ? ` — ${r.why}` : "";
     const errReason = r.errorReason ? ` reason=${r.errorReason}` : "";
-    lines.push(`${status} [${sev}] ${r.source}:${r.path} expected=${r.expected} actual=${r.actual} status=${r.status === null ? "?" : r.status}${errReason}${why}`);
+    const bodyTag = r.bodyCheck && r.bodyCheck !== "body_check_skipped" ? ` body=${r.bodyCheck}` : "";
+    lines.push(`${status} [${sev}] ${r.source}:${r.path} expected=${r.expected} actual=${r.actual} status=${r.status === null ? "?" : r.status}${errReason}${bodyTag}${why}`);
   }
   lines.push("END_CIPHERWAKE_ROUTE_ASSERTIONS");
   return color("dim", lines.join("\n"));
@@ -3810,15 +3945,41 @@ async function runTrustDiffCommand(args) {
     const effectiveShipWithAssertions = assertionShipImpact
       ? (SHIP_DECISION_RANK[assertionShipImpact] > SHIP_DECISION_RANK[effectiveShip] ? assertionShipImpact : effectiveShip)
       : effectiveShip;
+    // R88 wave 2 + R89 — fold in deploy health, secrets, cookies.
+    const dh = routeAssertions?.deployHealth || null;
+    const sc = routeAssertions?.secrets || null;
+    const cr2 = routeAssertions?.cookieResults || null;
     const assertionFields = routeAssertions ? {
       assertions_total: routeAssertions.total,
       assertions_passed: routeAssertions.passed,
       assertions_failed: routeAssertions.failed,
       assertions_critical_failures: routeAssertions.criticalFailures.length,
-      assertions_sources: `customer=${routeAssertions.sources.customer},default=${routeAssertions.sources.default},auto=${routeAssertions.sources.auto},auto_suppressed=${routeAssertions.sources.autoSuppressed || 0}`,
+      assertions_sources: `customer=${routeAssertions.sources.customer},default=${routeAssertions.sources.default},auto=${routeAssertions.sources.auto},auto_suppressed=${routeAssertions.sources.autoSuppressed || 0},dismissed=${routeAssertions.sources.dismissed || 0}`,
       assertion_top_failure: routeAssertions.criticalFailures[0]
         ? `${routeAssertions.criticalFailures[0].path}: expected ${routeAssertions.criticalFailures[0].expected}, got ${routeAssertions.criticalFailures[0].actual}`
         : undefined,
+      // Deploy health
+      deploy_status: dh?.status,
+      deploy_http_status: dh?.httpStatus,
+      deploy_summary: dh?.summary?.slice(0, 200),
+      ship_decision_health: dh && dh.status !== "healthy" && dh.status !== "unreachable" ? "block" : (dh ? "pass" : undefined),
+      // Secret scanner
+      secrets_scanned: sc?.scanned,
+      secrets_findings_total: sc?.findings?.length,
+      secrets_critical_count: sc?.criticalCount,
+      ship_decision_secrets: sc && sc.criticalCount > 0 ? "block" : (sc && sc.findings.length > 0 ? "review" : (sc ? "pass" : undefined)),
+      // Cookie invariants
+      cookie_failed: cr2 ? cr2.filter((c) => !c.passed).length : undefined,
+      cookie_critical_failures: routeAssertions.cookieCriticalFailures || 0,
+      ship_decision_cookies: cr2 && cr2.length > 0
+        ? (routeAssertions.cookieCriticalFailures > 0 ? "block" : (cr2.filter((c) => !c.passed).length > 0 ? "review" : "pass"))
+        : undefined,
+      // R90 — TLS expiry
+      tls_days_remaining: routeAssertions.tlsExpiry?.daysRemaining,
+      tls_passed: routeAssertions.tlsExpiry?.passed,
+      ship_decision_tls: routeAssertions.tlsExpiry?.checked
+        ? (routeAssertions.tlsExpiry.passed ? "pass" : (routeAssertions.tlsExpiry.severity === "critical" ? "block" : "review"))
+        : undefined,
     } : {};
 
     console.log(formatAiFooterBlock({
@@ -3842,13 +4003,63 @@ async function runTrustDiffCommand(args) {
       quota_limit: result.quota?.monthly_limit ?? undefined,
       scanned_at: new Date().toISOString(),
       advisory_only: "true",
-      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture_plus_route_assertions" : "trust_surface_drift_plus_route_assertions",
-      scope_note: "ship_decision = worst-of(drift, route_assertions" + (strictPosture ? ", absolute_posture)" : ")") + ". Route assertions verify your declared private routes (e.g. /api/admin) are still gated; any critical failure (protected route now exposed) blocks the deploy unconditionally. Posture is " + (strictPosture ? "also gated due to --strict-posture." : "advisory unless --strict-posture is set.") + " Cipherwake does NOT verify app functionality.",
+      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture_plus_route_assertions_plus_health" : "trust_surface_drift_plus_route_assertions_plus_health",
+      scope_note: "ship_decision = worst-of(drift, route_assertions, deploy_health, secret_scan, cookie_invariants" + (strictPosture ? ", absolute_posture)" : ")") + ". Cipherwake checked the public trust surface independently of what your AI coder claims; this is the gate that should fire before the AI announces a deploy. Cipherwake does NOT verify app functionality.",
+      narrative: routeAssertions
+        ? buildTrustDiffNarrative({
+            deltaCount: deltas.length,
+            assertionsFailedCount: routeAssertions.failed,
+            assertionsCriticalCount: routeAssertions.criticalFailures.length,
+            deployStatus: routeAssertions.deployHealth?.status,
+            secretsCriticalCount: routeAssertions.secrets?.criticalCount || 0,
+            secretsFindingsTotal: routeAssertions.secrets?.findings?.length || 0,
+            cookieFailedCount: (routeAssertions.cookieResults || []).filter((c) => !c.passed).length,
+            headerFailedCount: (routeAssertions.headerResults || []).filter((r) => !r.passed).length,
+            posture: posture?.grade,
+          })
+        : undefined,
       ...assertionFields,
       ...postureFields,
     }));
     if (routeAssertions) {
       console.log(formatRouteAssertionsBlock(routeAssertions));
+      // R89.LOCAL — persist local stats. ZERO network requests.
+      // R90 — also record surface snapshot for B/C (new-routes / new-scripts diff)
+      try {
+        const { recordResults, recordSurfaceSnapshot } = await import(new URL("./statsTracker.js", import.meta.url).href);
+        await recordResults(extractStatsEntries(routeAssertions));
+        // Extract publicRoutes + thirdPartyHosts from the report for snapshot
+        const publicRoutes = Array.isArray(currentReport?.publicRoutes?.paths)
+          ? currentReport.publicRoutes.paths.filter((p) => p.classification === "public").map((p) => p.path)
+          : [];
+        const thirdPartyHosts = Array.isArray(currentReport?.publicDeps?.thirdParties)
+          ? [...new Set(currentReport.publicDeps.thirdParties.map((t) => t.host).filter(Boolean))]
+          : [];
+        const certDaysToExpiry = typeof currentReport?.publicSurface?.daysUntilCertExpiry === "number"
+          ? currentReport.publicSurface.daysUntilCertExpiry
+          : null;
+        const surfaceDiff = await recordSurfaceSnapshot({ domain, publicRoutes, thirdPartyHosts, certDaysToExpiry });
+        if (surfaceDiff && (surfaceDiff.newRoutes.length > 0 || surfaceDiff.newHosts.length > 0 || surfaceDiff.removedRoutes.length > 0 || surfaceDiff.removedHosts.length > 0)) {
+          console.log("");
+          console.log(color("dim", "CIPHERWAKE_SURFACE_DIFF"));
+          console.log(color("dim", `prev_snapshot_at=${surfaceDiff.prevSnapshotAt}`));
+          for (const r of surfaceDiff.newRoutes) {
+            console.log(color("yellow", `NEW_PUBLIC_ROUTE: ${r}  — was not publicly reachable in last deploy. Review intent.`));
+          }
+          for (const r of surfaceDiff.removedRoutes) {
+            console.log(color("dim", `REMOVED_PUBLIC_ROUTE: ${r}  — was publicly reachable in last deploy.`));
+          }
+          for (const h of surfaceDiff.newHosts) {
+            console.log(color("red", `NEW_THIRD_PARTY_SCRIPT: ${h}  — supply-chain alert: a new third-party script appeared on your homepage since last deploy. Verify intent (vendor add) or investigate (injection / compromise).`));
+          }
+          for (const h of surfaceDiff.removedHosts) {
+            console.log(color("dim", `REMOVED_THIRD_PARTY_SCRIPT: ${h}  — third-party script removed since last deploy.`));
+          }
+          console.log(color("dim", "END_CIPHERWAKE_SURFACE_DIFF"));
+        }
+      } catch {
+        // never block on stats failures
+      }
     }
     if (posture && Array.isArray(posture.fixes) && posture.fixes.length > 0) {
       console.log(formatPostureFixesBlock(posture.fixes));
@@ -4957,6 +5168,132 @@ function renderReleaseChecklist(domain, opts = {}) {
 const VALID_FAIL_ON = ["any", "low", "medium", "high", "critical"];
 const VALID_BASELINES = ["last-week", "last-month", "last-scan"];
 
+// R89.LOCAL — `pqcheck stats` reads .cipherwake/stats.json + prints
+// per-check stats. ZERO network requests. Privacy-by-design.
+async function runStatsCommand(args) {
+  const { loadStats, formatStatsTable } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const stats = await loadStats();
+  console.log(formatStatsTable(stats));
+  console.log("");
+  console.log(color("dim", "Stats are local-only. They never leave your machine. Add .cipherwake/ to .gitignore if you don't want to commit them."));
+}
+
+async function runDismissCommand(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(color("red", "error: pqcheck dismiss requires a check id"));
+    console.error(color("dim", "Usage: pqcheck dismiss route:/admin/ideas    OR    pqcheck dismiss header:Strict-Transport-Security"));
+    process.exit(3);
+  }
+  const { markDismissed } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const path = await markDismissed(id);
+  if (path) {
+    console.log(color("green", `✓ Marked "${id}" as dismissed-intentional in ${path}`));
+  } else {
+    console.error(color("red", `error: could not persist dismissal for "${id}"`));
+    process.exit(1);
+  }
+}
+
+async function runConfirmCommand(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(color("red", "error: pqcheck confirm requires a check id"));
+    console.error(color("dim", "Usage: pqcheck confirm route:/admin/ideas   — marks as a confirmed real catch (a regression was fixed)"));
+    process.exit(3);
+  }
+  const { markConfirmed } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const path = await markConfirmed(id);
+  if (path) {
+    console.log(color("green", `✓ Marked "${id}" as confirmed-real in ${path}`));
+  } else {
+    console.error(color("red", `error: could not persist confirmation for "${id}"`));
+    process.exit(1);
+  }
+}
+
+// R89.LOCAL — extract per-check entries from a trust-diff response for
+// stats recording. Records ZERO network requests beyond what the probe
+// already made.
+function extractStatsEntries(routeAssertions) {
+  const entries = [];
+  if (!routeAssertions) return entries;
+  // Route assertions
+  for (const r of routeAssertions.results || []) {
+    entries.push({
+      id: `route:${r.path}`,
+      result: r.passed ? "pass" : "fail",
+      status: r.status,
+      severity: r.severity,
+      source: r.source,
+    });
+  }
+  // Header invariants
+  for (const h of routeAssertions.headerResults || []) {
+    entries.push({
+      id: `header:${h.header}`,
+      result: h.passed ? "pass" : "fail",
+      status: null,
+      severity: h.severity,
+      source: "customer",
+    });
+  }
+  // Cookie invariants
+  for (const c of routeAssertions.cookieResults || []) {
+    entries.push({
+      id: `cookie:${c.namePattern}`,
+      result: c.passed ? "pass" : "fail",
+      status: null,
+      severity: c.severity,
+      source: "customer",
+    });
+  }
+  // Secret scanner findings (each finding is its own check)
+  if (routeAssertions.secrets) {
+    if (routeAssertions.secrets.findings.length === 0 && routeAssertions.secrets.scanned) {
+      entries.push({
+        id: "secret:scan",
+        result: "pass",
+        status: null,
+        severity: "info",
+        source: "secret",
+      });
+    } else {
+      for (const f of routeAssertions.secrets.findings) {
+        entries.push({
+          id: `secret:${f.patternId}`,
+          result: "fail",
+          status: null,
+          severity: f.severity,
+          source: "secret",
+        });
+      }
+    }
+  }
+  // Deploy health
+  if (routeAssertions.deployHealth) {
+    const dh = routeAssertions.deployHealth;
+    entries.push({
+      id: "health:homepage",
+      result: dh.status === "healthy" ? "pass" : "fail",
+      status: dh.httpStatus,
+      severity: dh.status === "healthy" ? "info" : "critical",
+      source: "health",
+    });
+  }
+  // R90 — TLS expiry
+  if (routeAssertions.tlsExpiry && routeAssertions.tlsExpiry.checked) {
+    entries.push({
+      id: "tls:expiry",
+      result: routeAssertions.tlsExpiry.passed ? "pass" : "fail",
+      status: routeAssertions.tlsExpiry.daysRemaining,
+      severity: routeAssertions.tlsExpiry.severity,
+      source: "tls",
+    });
+  }
+  return entries;
+}
+
 async function runInitCommand(args) {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");

package/bin/statsTracker.js

@@ -0,0 +1,257 @@
+// =============================================================================
+// Local-only check stats (R89.LOCAL — 2026-06-05)
+// =============================================================================
+// Persists per-assertion / per-check stats to .cipherwake/stats.json in the
+// customer's repo. Records every result the CIPHERWAKE_* blocks already
+// print to stdout — pass/fail, status, severity, source, timestamp — so the
+// customer can later see (via `pqcheck stats`) which checks actually
+// catch real things vs. sit silent or false-flag.
+//
+// HARD RULE — privacy guarantee:
+//   This module emits ZERO network requests. It only writes to a local file.
+//   No telemetry, no analytics, no cross-repo aggregation. The customer's
+//   results stay on their machine. This matches Cipherwake's "no credentials"
+//   stance — "no credentials and now no data exhaust either."
+//
+// Cross-repo aggregation is a SEPARATE opt-in feature (paid tier hosted
+// analytics) that requires explicit account configuration. That path is
+// not implemented in this CLI module.
+// =============================================================================
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const STATS_DIR = ".cipherwake";
+const STATS_FILE = "stats.json";
+
+/**
+ * Stats entry shape per check id. Check ids follow a stable scheme:
+ *   route:<path>            — route assertion
+ *   header:<header-name>    — header invariant
+ *   cookie:<name-pattern>   — cookie invariant
+ *   secret:<pattern-id>     — secret scanner finding
+ *   deployHealth            — deploy-not-broken
+ *
+ * @typedef {Object} CheckStats
+ * @property {number} runs
+ * @property {number} passed
+ * @property {number} failed
+ * @property {number} confirmedReal      — incremented when a previously-failing check now passes (inferred fix)
+ * @property {number} dismissedIntentional — incremented when the customer marks the failure as intentional
+ * @property {"pass"|"fail"|"unknown"} lastResult
+ * @property {number|null} lastStatus
+ * @property {string} lastSeenAt   — ISO timestamp
+ * @property {string} severity     — last severity seen
+ * @property {string} source       — "customer" | "default" | "auto" | "health" | "secret"
+ */
+
+/**
+ * Walk up from cwd to find the nearest repo root (.cipherwake.json or .git).
+ * Stats file lives in <repo-root>/.cipherwake/stats.json.
+ */
+async function findStatsDir() {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, ".cipherwake.json")) || existsSync(join(dir, ".git"))) {
+      return join(dir, STATS_DIR);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback: write to cwd
+  return join(process.cwd(), STATS_DIR);
+}
+
+/**
+ * Load stats.json from disk. Returns empty stats object if missing or
+ * malformed (we never crash the deploy-check on stats issues).
+ */
+export async function loadStats() {
+  try {
+    const statsDir = await findStatsDir();
+    const path = join(statsDir, STATS_FILE);
+    if (!existsSync(path)) return { version: 1, checks: {} };
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !parsed.checks) return { version: 1, checks: {} };
+    return parsed;
+  } catch {
+    return { version: 1, checks: {} };
+  }
+}
+
+/**
+ * Persist stats.json. Creates .cipherwake/ if missing.
+ */
+async function persistStats(stats) {
+  try {
+    const statsDir = await findStatsDir();
+    if (!existsSync(statsDir)) {
+      await mkdir(statsDir, { recursive: true });
+    }
+    const path = join(statsDir, STATS_FILE);
+    await writeFile(path, JSON.stringify(stats, null, 2), "utf8");
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply a batch of check outcomes from a single deploy-check run. Each entry:
+ *   { id, result: "pass"|"fail", status, severity, source }
+ *
+ * Inferred confirmedReal: when the previous lastResult was "fail" and the
+ * new result is "pass", increment confirmedReal. This catches the "I fixed
+ * the regression Cipherwake flagged" event.
+ */
+export async function recordResults(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  const stats = await loadStats();
+  const now = new Date().toISOString();
+  for (const e of entries) {
+    if (!e || typeof e.id !== "string") continue;
+    const cur = stats.checks[e.id] || {
+      runs: 0,
+      passed: 0,
+      failed: 0,
+      confirmedReal: 0,
+      dismissedIntentional: 0,
+      lastResult: "unknown",
+      lastStatus: null,
+      lastSeenAt: now,
+      severity: e.severity || "low",
+      source: e.source || "default",
+    };
+    cur.runs += 1;
+    if (e.result === "pass") {
+      cur.passed += 1;
+      if (cur.lastResult === "fail") cur.confirmedReal += 1;
+      cur.lastResult = "pass";
+    } else if (e.result === "fail") {
+      cur.failed += 1;
+      cur.lastResult = "fail";
+    }
+    cur.lastStatus = (typeof e.status === "number" || e.status === null) ? e.status : cur.lastStatus;
+    cur.lastSeenAt = now;
+    cur.severity = e.severity || cur.severity;
+    cur.source = e.source || cur.source;
+    stats.checks[e.id] = cur;
+  }
+  return await persistStats(stats);
+}
+
+/**
+ * Mark a check as dismissed-intentional. Customer ran `pqcheck dismiss <id>`
+ * after reviewing it as a false positive / intentional state.
+ */
+export async function markDismissed(id) {
+  if (typeof id !== "string" || !id) return null;
+  const stats = await loadStats();
+  const cur = stats.checks[id] || { runs: 0, passed: 0, failed: 0, confirmedReal: 0, dismissedIntentional: 0, lastResult: "unknown", lastStatus: null, lastSeenAt: new Date().toISOString(), severity: "low", source: "customer" };
+  cur.dismissedIntentional += 1;
+  cur.lastSeenAt = new Date().toISOString();
+  stats.checks[id] = cur;
+  return await persistStats(stats);
+}
+
+/**
+ * Mark a check as a confirmed real catch (used by `pqcheck confirm <id>`
+ * when the customer wants to record it explicitly rather than relying on
+ * the inferred-from-fix mechanism).
+ */
+export async function markConfirmed(id) {
+  if (typeof id !== "string" || !id) return null;
+  const stats = await loadStats();
+  const cur = stats.checks[id] || { runs: 0, passed: 0, failed: 0, confirmedReal: 0, dismissedIntentional: 0, lastResult: "unknown", lastStatus: null, lastSeenAt: new Date().toISOString(), severity: "low", source: "customer" };
+  cur.confirmedReal += 1;
+  cur.lastSeenAt = new Date().toISOString();
+  stats.checks[id] = cur;
+  return await persistStats(stats);
+}
+
+/**
+ * R90 (2026-06-05) — record snapshot of "what's on the public surface" so
+ * the next deploy-check can diff it. Captures:
+ *   - publicRoutes: list of /privacy, /terms, etc. paths returning 200
+ *   - thirdPartyHosts: list of third-party script hosts loaded by the homepage
+ *   - certDaysToExpiry: TLS cert remaining days
+ *
+ * Compared against the prior snapshot at next-deploy time to emit
+ * "new since last deploy" diffs (B and C in the final build brief).
+ * Snapshots live in .cipherwake/stats.json (local, no transmission).
+ *
+ * Returns the diff vs the prior snapshot (or null if this is the first run).
+ */
+export async function recordSurfaceSnapshot(snapshot) {
+  try {
+    const stats = await loadStats();
+    if (!stats.surfaceSnapshots) stats.surfaceSnapshots = {};
+    const now = new Date().toISOString();
+    const prev = stats.surfaceSnapshots[snapshot.domain] || null;
+    const diff = computeSurfaceDiff(prev, snapshot);
+    stats.surfaceSnapshots[snapshot.domain] = {
+      capturedAt: now,
+      publicRoutes: snapshot.publicRoutes || [],
+      thirdPartyHosts: snapshot.thirdPartyHosts || [],
+      certDaysToExpiry: snapshot.certDaysToExpiry ?? null,
+    };
+    await persistStats(stats);
+    return diff;
+  } catch {
+    return null;
+  }
+}
+
+function computeSurfaceDiff(prev, current) {
+  if (!prev) return null;
+  const prevRoutes = new Set(prev.publicRoutes || []);
+  const currRoutes = new Set(current.publicRoutes || []);
+  const prevHosts = new Set(prev.thirdPartyHosts || []);
+  const currHosts = new Set(current.thirdPartyHosts || []);
+  return {
+    newRoutes: [...currRoutes].filter((r) => !prevRoutes.has(r)),
+    removedRoutes: [...prevRoutes].filter((r) => !currRoutes.has(r)),
+    newHosts: [...currHosts].filter((h) => !prevHosts.has(h)),
+    removedHosts: [...prevHosts].filter((h) => !currHosts.has(h)),
+    prevSnapshotAt: prev.capturedAt,
+  };
+}
+
+/**
+ * Format stats as a human-readable table for `pqcheck stats`.
+ */
+export function formatStatsTable(stats) {
+  const ids = Object.keys(stats.checks || {}).sort();
+  if (ids.length === 0) return "No check results recorded yet. Run `pqcheck deploy-check` to start.";
+  const lines = [];
+  lines.push("Cipherwake check stats (local, never transmitted)");
+  lines.push("=" .repeat(96));
+  lines.push("CHECK".padEnd(40) + " RUNS  PASS  FAIL  CONFIRMED  DISMISSED  LAST  SEVERITY");
+  lines.push("-" .repeat(96));
+  for (const id of ids) {
+    const s = stats.checks[id];
+    const last = s.lastResult || "?";
+    lines.push(
+      id.slice(0, 39).padEnd(40) +
+      String(s.runs).padStart(5) +
+      String(s.passed).padStart(6) +
+      String(s.failed).padStart(6) +
+      String(s.confirmedReal).padStart(11) +
+      String(s.dismissedIntentional).padStart(11) +
+      " " + last.padEnd(5) +
+      " " + (s.severity || "?")
+    );
+  }
+  lines.push("-" .repeat(96));
+  const totalRuns = ids.reduce((a, id) => a + (stats.checks[id].runs || 0), 0);
+  const totalFailed = ids.reduce((a, id) => a + (stats.checks[id].failed || 0), 0);
+  const totalConfirmed = ids.reduce((a, id) => a + (stats.checks[id].confirmedReal || 0), 0);
+  const totalDismissed = ids.reduce((a, id) => a + (stats.checks[id].dismissedIntentional || 0), 0);
+  const catchRate = totalFailed > 0 ? ((totalConfirmed / totalFailed) * 100).toFixed(0) : "—";
+  lines.push(`TOTAL: ${ids.length} checks tracked, ${totalRuns} runs, ${totalFailed} failures, ${totalConfirmed} confirmed real, ${totalDismissed} dismissed.`);
+  lines.push(`Confirmed-catch rate: ${catchRate}% of failures were confirmed real (a fix landed afterward).`);
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.16.24",
+  "version": "0.16.29",
   "description": "Deploy gate for AI-coded web apps. `pqcheck deploy-check --ai` returns ship_decision=pass|review|block for Claude Code / Cursor / Copilot / Aider to gate deploys before they ship. Anonymous, no signup, free for first use.",
   "keywords": [
     "ai-coder",