pqcheck 0.16.21 → 0.16.23

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.21** — `ship_decision` now folds posture into the headline routing decision (worst-of drift + posture) — closes a footgun where a clean-drift F-posture deploy would have shipped under the original "`pass` → announce" protocol. Posture rubric recalibrated for partial credit: a site with valid HSTS preload + everything else missing now scores ~29 / grade D, not 0 / F. Fix snippets now emit inline in a `CIPHERWAKE_POSTURE_FIXES` block — no JSON round-trip needed to read them. Empty legacy `grade=` field dropped from the AI block. [Full changelog →](./CHANGELOG.md)
+> **Latest: v0.16.23** — Closes the silent-no-op flag class. `--strict` now aliases `--strict-posture` in scan / deploy-check / trust-diff (audit caught the typo silently degrading to drift-only). And unknown flags now reject loudly with a closest-match suggestion + non-zero exit — `--stict-posture` (typo) → `error: did you mean --strict-posture?` instead of silently no-op'ing. Same principle applied to ourselves that Cipherwake exists to enforce for customers: a security tool can never silently proceed with weaker behaviour on an unrecognized signal. [Full changelog →](./CHANGELOG.md)
 
 ## Two ways to use it
 

package/bin/pqcheck.js

@@ -248,6 +248,14 @@ async function main() {
     }
   }
 
+  // R86.7 — reject unknown flags loudly. Catches typo'd safety-critical
+  // flags like `--strict` (was intended --strict-posture) that previously
+  // silently no-op'd, leaving customers with a false sense of security.
+  const unknown = assertKnownFlags(args, "pqcheck <domain>");
+  if (unknown) {
+    process.exit(3);
+  }
+
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
   const domains = [...positional, ...fileDomains]
     .map((a) => normalizeDomain(a))
@@ -290,17 +298,29 @@ async function main() {
   const fresh = args.includes("--fresh") || args.includes("--force");
   const aiMode = parseAiMode(args);
   const verbose = isVerboseMode(args);  // v0.16.0 — opt-in detailed panel
+  // R86.4 (2026-06-03) — strict-posture opt-in. Default ship_decision is
+  // drift-only (per-deploy regression gate); --strict-posture folds the
+  // absolute posture grade into ship_decision. Recommended ONLY after a
+  // site reaches A/B posture — opting in earlier produces cry-wolf gating
+  // on every deploy since most AI-coded sites grade D/F out of the box.
+  // Accept both `--strict-posture` (explicit) and `--strict` (short alias).
+  // Audit caught a footgun where customers typed `--strict` expecting the
+  // posture gate to fire and got silent drift-only mode instead. The
+  // `onboard` subcommand uses `--strict` for a different purpose (gate exit
+  // code on step failure) but that's a separate command — the alias is
+  // scoped to scan / deploy-check / trust-diff only.
+  const strictPosture = args.includes("--strict-posture") || args.includes("--strict");
 
   // One-shot scan(s)
   let worstExit = 0;
   for (const domain of domains) {
-    const exit = await runOneScan({ domain, format, quiet, threshold, webhookUrl, multi: domains.length > 1, fresh, aiMode, verbose });
+    const exit = await runOneScan({ domain, format, quiet, threshold, webhookUrl, multi: domains.length > 1, fresh, aiMode, verbose, strictPosture });
     if (exit > worstExit) worstExit = exit;
   }
   process.exit(worstExit);
 }
 
-async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi, fresh, aiMode, verbose }) {
+async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi, fresh, aiMode, verbose, strictPosture }) {
   if (!quiet && format === "text") process.stderr.write(color("dim", `Scanning ${domain}${fresh ? " (forcing fresh)" : ""} ...`));
   let report;
   try {
@@ -511,7 +531,13 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
       posture_findings_count: (posture.findings || []).length,
       posture_fixes_count: (posture.fixes || []).length,
     } : {};
-    const effectiveShip = combineShipDecision(shipDecision, posture?.decision);
+    // R86.2 (2026-06-03) — see combineShipDecision: posture is advisory by
+    // default, gated when --strict-posture is passed.
+    const effectiveShip = combineShipDecision(shipDecision, posture?.decision, { strict: strictPosture });
+    // R86.5 — surface posture advisory line so D/F posture is never silently
+    // blessed under the drift-only default.
+    const postureAdvisory = formatPostureAdvisoryLine(posture, strictPosture);
+    if (postureAdvisory) console.log(postureAdvisory);
     console.log(formatAiFooterBlock({
       status: effectiveShip,
       domain,
@@ -522,14 +548,17 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
       ship_decision: effectiveShip,
       ship_decision_drift: shipDecision,
       ship_decision_posture: posture?.decision,
+      ship_decision_mode: strictPosture ? "strict_posture" : "drift_only",
       unreachable: unreachable ? "true" : "false",
       top_issue: topFinding?.id || topFinding?.title || "none",
       findings_high: findings.filter((f) => severityRank(f.severity) === 3).length,
       findings_critical: findings.filter((f) => severityRank(f.severity) === 4).length,
       scanned_at: new Date().toISOString(),
       advisory_only: "true",
-      scope: "trust_surface_drift_plus_absolute_posture",
-      scope_note: "ship_decision = worst-of(drift, absolute posture). pass means BOTH no drift AND posture grade A+/A. ship_decision_drift and ship_decision_posture expose the two inputs separately. Cipherwake does NOT verify app functionality — pair with Playwright e2e for full deploy safety.",
+      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture" : "trust_surface_drift",
+      scope_note: strictPosture
+        ? "ship_decision = worst-of(drift, absolute posture) because --strict-posture is set. pass means BOTH no drift AND posture grade A+/A. ship_decision_drift and ship_decision_posture expose the two inputs separately. Cipherwake does NOT verify app functionality — pair with Playwright e2e for full deploy safety."
+        : "ship_decision reflects DRIFT only by default (per-deploy regression gate). Posture grade is surfaced via posture_decision / ship_decision_posture as advisory — D/F posture does NOT auto-block. Once your site reaches A/B posture, pass --strict-posture to lock that in. Cipherwake does NOT verify app functionality.",
       ...postureFields,
     }));
     if (posture && Array.isArray(posture.fixes) && posture.fixes.length > 0) {
@@ -573,6 +602,14 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
   } else {
     if (multi) console.log(color("dim", `\n──── ${domain} ────`));
     printReport(report);
+    // R86.5 — posture advisory line so D/F posture is never silently blessed
+    // in human output either. Posture is advisory, not gating.
+    const postureAdvisory = formatPostureAdvisoryLine(report.posture, strictPosture);
+    if (postureAdvisory) {
+      console.log("");
+      console.log(postureAdvisory);
+      console.log(color("dim", "  See /methodology/posture-grading for the rubric + fix snippets."));
+    }
   }
 
   if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
@@ -724,6 +761,100 @@ function parseAiMode(args) {
   return args.includes("--ai") || args.includes("--agent");
 }
 
+// R86.7 (2026-06-04) — close the "silent no-op on unrecognized flag" class
+// of footguns. Audit caught --strict (intended --strict-posture) silently
+// degrading to drift-only mode without warning — the user believed they had
+// the hard posture gate on. Same family as false-green pins: looks like it's
+// doing something, silently isn't. The fix: validate every --foo token in
+// args against a known-flags whitelist and reject loudly on unknown flags
+// with a closest-match suggestion. For a security gate, "unknown flag →
+// silently proceed with weaker behaviour" must never happen.
+//
+// Scope: universal whitelist applied at scan / deploy-check / trust-diff /
+// preview-diff entry points. False acceptance of cross-command flags (e.g.
+// passing --preview to deploy-check) is the SAME failure mode as today
+// (silent ignore) — typo detection is the win. Per-command whitelists
+// would be more correct but the universal list covers the audit footgun.
+const KNOWN_FLAGS = new Set([
+  // Global / output mode
+  "--ai", "--agent", "--verbose", "--quiet", "--help", "--version", "--debug-network",
+  // Multi-domain
+  "--file", "--watch",
+  // Scan behaviour
+  "--fresh", "--force", "--threshold", "--webhook", "--json", "--csv", "--markdown",
+  "--sarif", "--gh-action", "--multi", "--lock", "--explain", "--plan", "--stdout",
+  // Posture gating (the audit catch)
+  "--strict", "--strict-posture",
+  // Format / output format
+  "--format",
+  // Trust-diff / deploy-check / preview-diff
+  "--baseline", "--fail-on", "--fail-on-new", "--guards", "--compare-transport",
+  "--write-baseline", "--preview", "--production",
+  // Setup / onboard / install consent
+  "--auto", "--manual", "--yes", "--no-open", "--domain", "--invoked-by",
+  "--consent-phrase", "--scope",
+  "--skip-checklist", "--skip-hook", "--skip-protocol", "--skip-scan",
+  "--skip-statusline", "--skip-vendors", "--skip-vscode", "--skip-workflow",
+]);
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const row = new Array(m + 1);
+  for (let i = 0; i <= m; i++) row[i] = i;
+  for (let j = 1; j <= n; j++) {
+    let prev = row[0];
+    row[0] = j;
+    for (let i = 1; i <= m; i++) {
+      const tmp = row[i];
+      row[i] = a[i - 1] === b[j - 1]
+        ? prev
+        : 1 + Math.min(prev, row[i], row[i - 1]);
+      prev = tmp;
+    }
+  }
+  return row[m];
+}
+
+function suggestFlag(unknown) {
+  let best = null, bestDist = Infinity;
+  for (const known of KNOWN_FLAGS) {
+    const d = levenshtein(unknown, known);
+    if (d < bestDist) { bestDist = d; best = known; }
+  }
+  // Only suggest if reasonably close (≤ 3 edits or ≤ half the unknown's length)
+  const threshold = Math.max(3, Math.floor(unknown.length / 2));
+  return bestDist <= threshold ? best : null;
+}
+
+function assertKnownFlags(args, cmdName) {
+  const unknown = [];
+  for (const tok of args) {
+    if (typeof tok !== "string" || !tok.startsWith("--") || tok === "--") continue;
+    // Strip `--foo=bar` → `--foo` so equals-value forms validate against the bare flag
+    const flag = tok.includes("=") ? tok.slice(0, tok.indexOf("=")) : tok;
+    if (!KNOWN_FLAGS.has(flag)) unknown.push(flag);
+  }
+  if (unknown.length === 0) return null;
+  // Emit error to stderr with closest-match suggestion, return non-null
+  // sentinel so the caller can exit non-zero. We do NOT process.exit here
+  // because the AI-mode caller needs to emit a structured guard block
+  // before exiting (so AI agents parsing the block don't see a missing
+  // CIPHERWAKE_AI_GUARD_RESULT and fall through to a different error path).
+  for (const u of unknown) {
+    const sug = suggestFlag(u);
+    process.stderr.write(color("red", `error: unknown flag ${u} for ${cmdName}\n`));
+    if (sug) {
+      process.stderr.write(color("yellow", `       did you mean ${sug}?\n`));
+    } else {
+      process.stderr.write(color("dim", `       run \`npx pqcheck --help\` for the flag list.\n`));
+    }
+  }
+  return unknown;
+}
+
 function severityRank(s) {
   const map = { critical: 4, high: 3, medium: 2, low: 1, info: 0, none: -1 };
   return map[String(s || "none").toLowerCase()] ?? 0;
@@ -738,45 +869,49 @@ function highestSeverity(findings) {
   return best;
 }
 
-// Compute ship_decision: pass | review | block.
-// Used in three contexts:
-//   - one-shot scan: severity-only, no diff baseline
-//   - trust-diff / preview-diff: severity + diff-since-baseline
-//   - deploy-check: same as trust-diff (it's an alias)
-//
-// Decision rules (advisory only):
-//   * `block`  — critical severity present
-//   * `review` — high severity OR diff introduced new high-severity OR DBR drop ≥1.0
-//   * `pass`   — everything else
-function computeShipDecision({ maxSeverity, hasUnexpectedDiff, scoreDelta }) {
-  const sev = String(maxSeverity || "none").toLowerCase();
-  if (sev === "critical") return "block";
-  if (sev === "high") return "review";
-  if (hasUnexpectedDiff) return "review";
-  if (typeof scoreDelta === "number" && scoreDelta <= -1.0) return "review";
-  return "pass";
+// R86.5 (2026-06-03) — posture advisory line. Posture is a STANDING property,
+// not a per-deploy regression signal, so gating every deploy on it is cry-wolf
+// by construction. The drift-only ship_decision is the right default gate
+// (fires on regression). This helper surfaces posture grade + a one-line fix
+// nudge alongside the gate result — customer sees the grade, sees the fix
+// path, is NOT blocked on every deploy. Only customers who have reached A/B
+// posture opt into --strict-posture to lock that in.
+function formatPostureAdvisoryLine(posture, strictPosture) {
+  if (!posture) return "";
+  if (strictPosture) return ""; // strict mode already gates; redundant
+  const decision = posture.decision;
+  if (decision !== "block" && decision !== "review") return ""; // A+/A — no advisory
+  const grade = posture.grade || "?";
+  const score = typeof posture.score === "number" ? posture.score : "?";
+  const fixCount = Array.isArray(posture.fixes) ? posture.fixes.length : 0;
+  const colorName = decision === "block" ? "red" : "yellow";
+  const icon = decision === "block" ? "●" : "○";
+  const nudge = fixCount > 0
+    ? `${fixCount} ready-to-paste fix${fixCount === 1 ? "" : "es"} in CIPHERWAKE_POSTURE_FIXES`
+    : "see /methodology/posture-grading";
+  return color(colorName, `  ${icon} Posture: ${grade} (score ${score}) — advisory, not gating. ${nudge}.`);
 }
 
-// R86.2 (2026-06-03) — fold absolute posture grade into ship_decision so an
-// AI agent following the original "ship_decision=pass → safe to announce"
-// protocol does NOT ship a site with F-grade posture just because nothing
-// drifted since last scan. The headline decision must reflect both drift
-// and absolute state.
-//
-// Order: block > review > pass. Worst-of-both wins.
+// R86.2 / R86.4 (2026-06-03) — combine drift + posture into ship_decision.
+// Default (strict=false): drift only. Posture grade is surfaced via separate
+// fields and the advisory line but does NOT promote drift's decision —
+// because most AI-coded sites grade D/F out of the box, making posture-gating
+// the default would cry-wolf on every deploy of every header-less site,
+// training people to ignore the gate. --strict-posture opts in for teams
+// who've already fixed posture and want to prevent backsliding.
 const SHIP_DECISION_RANK = { pass: 0, review: 1, block: 2 };
-function combineShipDecision(driftDecision, postureDecision) {
-  if (!postureDecision) return driftDecision;
+function combineShipDecision(driftDecision, postureDecision, { strict = false } = {}) {
+  if (!postureDecision || !strict) return driftDecision;
   const a = SHIP_DECISION_RANK[driftDecision] ?? 0;
   const b = SHIP_DECISION_RANK[postureDecision] ?? 0;
   return a >= b ? driftDecision : postureDecision;
 }
 
 // R86.3 (2026-06-03) — emit per-finding fix snippets in a separate parseable
-// block after the AI guard block. The guard block stays compact key=value; the
+// block after the AI guard block. The guard block stays compact key=value;
 // fixes are multi-line code so they get their own block with explicit
-// start/end markers + per-fix delimiters. Agents can parse the fixes
-// independently and apply them without round-tripping to the JSON response.
+// start/end markers + per-fix delimiters. Agents parse + apply without
+// round-tripping to JSON.
 function formatPostureFixesBlock(fixes) {
   if (!Array.isArray(fixes) || fixes.length === 0) return "";
   const lines = ["", "CIPHERWAKE_POSTURE_FIXES"];
@@ -797,6 +932,25 @@ function formatPostureFixesBlock(fixes) {
   return color("dim", lines.join("\n"));
 }
 
+// Compute ship_decision: pass | review | block.
+// Used in three contexts:
+//   - one-shot scan: severity-only, no diff baseline
+//   - trust-diff / preview-diff: severity + diff-since-baseline
+//   - deploy-check: same as trust-diff (it's an alias)
+//
+// Decision rules (advisory only):
+//   * `block`  — critical severity present
+//   * `review` — high severity OR diff introduced new high-severity OR DBR drop ≥1.0
+//   * `pass`   — everything else
+function computeShipDecision({ maxSeverity, hasUnexpectedDiff, scoreDelta }) {
+  const sev = String(maxSeverity || "none").toLowerCase();
+  if (sev === "critical") return "block";
+  if (sev === "high") return "review";
+  if (hasUnexpectedDiff) return "review";
+  if (typeof scoreDelta === "number" && scoreDelta <= -1.0) return "review";
+  return "pass";
+}
+
 function aiBannerColor(shipDecision) {
   if (shipDecision === "pass") return "green";
   if (shipDecision === "block") return "red";
@@ -3319,10 +3473,16 @@ async function runScanBasedDeployCheck(domain, args) {
 }
 
 async function runTrustDiffCommand(args) {
+  // R86.7 — reject unknown flags before any other parsing. Same rationale
+  // as the bare-scan path: typo'd safety-critical flags must fail loud,
+  // not silently degrade.
+  if (assertKnownFlags(args, "pqcheck trust-diff")) {
+    process.exit(3);
+  }
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
   if (positional.length === 0) {
     console.error(color("red", "error: pqcheck trust-diff requires a domain"));
-    console.error(color("dim", "Usage: npx pqcheck trust-diff <domain> [--baseline last-week] [--fail-on high] [--format pretty|json|sarif|github]"));
+    console.error(color("dim", "Usage: npx pqcheck trust-diff <domain> [--baseline last-week] [--fail-on high] [--format pretty|json|sarif|github] [--strict-posture]"));
     process.exit(3);
   }
   const domain = normalizeDomain(positional[0]);
@@ -3334,6 +3494,17 @@ async function runTrustDiffCommand(args) {
   const baseline = parseFlag(args, "--baseline") || "last-week";
   const failOn = parseFlag(args, "--fail-on") || "high";
   const format = parseFlag(args, "--format") || "pretty";
+  // R86.4 (2026-06-03) — see runOneScan for rationale. Default ship_decision
+  // is drift-only (per-deploy regression gate); --strict-posture opts into
+  // worst-of(drift, posture). Recommended only after a site reaches A/B
+  // posture to lock that in.
+  // Accept both `--strict-posture` (explicit) and `--strict` (short alias).
+  // Audit caught a footgun where customers typed `--strict` expecting the
+  // posture gate to fire and got silent drift-only mode instead. The
+  // `onboard` subcommand uses `--strict` for a different purpose (gate exit
+  // code on step failure) but that's a separate command — the alias is
+  // scoped to scan / deploy-check / trust-diff only.
+  const strictPosture = args.includes("--strict-posture") || args.includes("--strict");
 
   // Build headers conditionally — Authorization is set ONLY if the user has
   // an API key. Without it, the server's applyRepoQuota falls through to the
@@ -3479,7 +3650,12 @@ async function runTrustDiffCommand(args) {
       posture_findings_count: (posture.findings || []).length,
       posture_fixes_count: (posture.fixes || []).length,
     } : {};
-    const effectiveShip = combineShipDecision(shipDecision, posture?.decision);
+    // R86.2 / R86.4 — see combineShipDecision: posture is advisory by default,
+    // gated only when --strict-posture is passed.
+    const effectiveShip = combineShipDecision(shipDecision, posture?.decision, { strict: strictPosture });
+    // R86.5 — surface posture advisory line in default (non-strict) mode.
+    const postureAdvisory = formatPostureAdvisoryLine(posture, strictPosture);
+    if (postureAdvisory) console.log(postureAdvisory);
     console.log(formatAiFooterBlock({
       status: effectiveShip,
       domain,
@@ -3491,6 +3667,7 @@ async function runTrustDiffCommand(args) {
       ship_decision: effectiveShip,
       ship_decision_drift: shipDecision,
       ship_decision_posture: posture?.decision,
+      ship_decision_mode: strictPosture ? "strict_posture" : "drift_only",
       top_issue: topDelta?.id || topDelta?.type || "none",
       top_issue_title: topDelta?.title || undefined,
       dbr: typeof result.current_score === "number" ? result.current_score.toFixed(1) : undefined,
@@ -3499,8 +3676,10 @@ async function runTrustDiffCommand(args) {
       quota_limit: result.quota?.monthly_limit ?? undefined,
       scanned_at: new Date().toISOString(),
       advisory_only: "true",
-      scope: "trust_surface_drift_plus_absolute_posture",
-      scope_note: "ship_decision = worst-of(drift, absolute posture). pass means BOTH no drift AND posture grade A+/A. ship_decision_drift and ship_decision_posture expose the two inputs separately. Cipherwake does NOT verify app functionality — pair with Playwright e2e for full deploy safety.",
+      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture" : "trust_surface_drift",
+      scope_note: strictPosture
+        ? "ship_decision = worst-of(drift, absolute posture) because --strict-posture is set. pass means BOTH no drift AND posture grade A+/A. ship_decision_drift and ship_decision_posture expose the two inputs separately. Cipherwake does NOT verify app functionality — pair with Playwright e2e for full deploy safety."
+        : "ship_decision reflects DRIFT only by default (per-deploy regression gate). Posture grade is surfaced via posture_decision / ship_decision_posture as advisory — D/F posture does NOT auto-block. Once your site reaches A/B posture, pass --strict-posture to lock that in. Cipherwake does NOT verify app functionality.",
       ...postureFields,
     }));
     if (posture && Array.isArray(posture.fixes) && posture.fixes.length > 0) {
@@ -3822,6 +4001,11 @@ async function runGuardsRunCommand(args) {
 }
 
 async function runPreviewDiffCommand(args) {
+  // R86.7 — reject unknown flags before parsing. Closes the silent-no-op
+  // class of footguns for the preview-diff command too.
+  if (assertKnownFlags(args, "pqcheck preview-diff")) {
+    process.exit(3);
+  }
   const previewUrl = parseFlag(args, "--preview");
   const productionUrl = parseFlag(args, "--production");
   if (!previewUrl || !productionUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.16.21",
+  "version": "0.16.23",
   "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",