ai-saas-guard 0.26.1 → 0.27.0

package/README.md

@@ -1,15 +1,15 @@
 <h1 align="center">ai-saas-guard</h1>
 
 <p align="center">
-  <strong>You used AI to build your SaaS. Now you need to know what is risky before launch.</strong>
+  <strong>You used AI to build your SaaS. Now find the launch risks before users do.</strong>
 </p>
 
 <p align="center">
-  ai-saas-guard points reviewers to the auth, billing, data access, secrets, MCP, and deploy changes that deserve human attention first. It runs locally, reads your repo only, and does not upload code.
+  ai-saas-guard is a local-first launch gate for AI-built SaaS apps. It focuses on auth, billing, data access, secrets, MCP, and deploy decisions, plus CI and fake-success paths, so you know what to review before launch or merge. It runs locally, reads your repo only, and does not upload code.
 </p>
 
 <p align="center">
-  It is not a pentest. It is a practical review checklist for launch-risk hotspots.
+  It is not a pentest. It is a practical, evidence-first review queue for the code that can break launch.
 </p>
 
 <p align="center">
@@ -27,40 +27,42 @@
 
 ---
 
-## The Problem It Solves
+## The Launch Problem
 
-AI can turn an idea into a working SaaS quickly. The harder question is whether the app is ready for real users.
+AI can make a SaaS look finished while the real launch blockers sit in trust-boundary code. These are the failures that hurt after real users arrive:
 
-The risky parts are often not the obvious UI bugs. They are the small changes that decide who can see data, who gets paid access, where secrets are exposed, and what an AI tool is allowed to do:
+- one customer can see or change another customer's data
+- Stripe grants access from an unsigned, duplicated, missing, or failed webhook path
+- provider errors get swallowed and the app returns fake success or demo data
+- a secret leaks through env config or `NEXT_PUBLIC_*`
+- an MCP tool, GitHub workflow, or deploy job has more power than the launch needs
+- a Next/Vercel deploy is missing production env docs, security headers, request IDs, or cost-risk hints
+- a large AI PR hides auth, billing, data, deploy, or test changes inside harmless-looking work
 
-- Can one customer read another customer's data?
-- Can a Stripe webhook grant access twice, miss a failed payment, or trust an unsigned request?
-- Did a public environment variable expose a secret?
-- Did an MCP tool get shell, database, or broad filesystem access?
-- Did AI-generated error handling return fake success or demo data after a real provider failed?
-- Will the Next/Vercel deploy have the headers, env docs, logging, and request behavior needed for launch?
-- Did a pull request hide auth, billing, or deploy changes inside a large AI-generated diff?
-
-`ai-saas-guard` is a local-first, review-first preflight for that moment. It does not try to prove your app is secure. It is not a pentest, certification, or full audit. It gives founders, solo builders, small teams, and reviewers a short, evidence-backed list of what to check before launch or merge.
+`ai-saas-guard` gives you a short local review queue for those risks. It does not prove the app is secure, certify a release, or replace human review. It tells founders, solo builders, small teams, and reviewers what deserves attention first.
 
 ## What You Get
 
-Run it against a repository or pull request and get findings with:
+One command returns a launch-readiness report with:
 
-- the rule that matched
-- severity and file evidence
-- why the issue matters in a SaaS launch
-- how to verify it manually
-- a practical fix direction
+- a plain launch-gate verdict at the top of terminal and Markdown output
+- risky files sorted before cosmetic files
+- rule ID, severity, and file evidence
+- why the finding matters for an AI-built SaaS launch
+- manual verification steps you can actually run
+- practical fix direction, not generic advice
+- terminal, JSON, SARIF, and PR markdown output for local review or CI
 
-It is built for common AI-SaaS stacks:
+## Problems It Helps You Catch
 
-- Next.js and Vercel
-- Supabase row-level security and storage policies
-- Stripe checkout, subscriptions, and webhooks
-- Prisma or SQL migrations
-- MCP server configuration
-- AI-generated pull requests with large mixed diffs
+| Launch question | What ai-saas-guard checks |
+| --- | --- |
+| Can users only access their own data? | Supabase RLS, tenant/owner predicates, storage policies, API ownership hints, two-account verification guidance |
+| Will billing change access correctly? | Stripe webhook signature, raw body, idempotency, entitlement paths, failure/cancel/update/refund coverage |
+| Will broken integrations fail visibly? | Silent-success fallbacks, swallowed errors, hardcoded success responses, production mock/demo data, skipped or placeholder tests |
+| Will production behave like local? | Next/Vercel headers, env docs, public env inventory, image/request amplification hints, request ID logging |
+| Are tools and CI overpowered? | MCP side-effect classes, local policy/receipt templates, GitHub Actions permissions, concurrency, checkout depth, action pinning |
+| Can reviewers trust the PR? | `pr-risk` ranking for auth, billing, RLS, deploy, API, storage, tests, silent-success paths, missing spec context, and large AI diffs |
 
 ## Current Status
 
@@ -71,24 +73,17 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | Published as `ai-saas-guard` |
-| Local CLI from source | Available for development |
-| JSON and SARIF output | Available |
-| Composite GitHub Action | Available |
-| Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.26.1`, `v0` |
-| npm package | `ai-saas-guard@0.26.1` |
-| Current release | `0.26.1` launch-risk expansion |
+| npm CLI | `ai-saas-guard@0.27.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.27.0` |
+| Outputs | Terminal, JSON, SARIF, and PR-focused markdown |
+| Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
+| Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
+| Versioned Action tags | `v0.27.0`, `v0` |
+| Current release | `0.27.0` launch-gate report summary for CLI and hosted Check Runs |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
-| Runtime hardening | Per-file and total text scan caps, escaped markdown evidence, 1 MiB hosted webhook payload cap, stricter hosted deployment blockers |
-| Hosted production adapters | GitHub App JWT signing, installation-token request planning, bounded worker execution, and terminal-state cleanup planning |
-| Hosted app skeleton | Node/container HTTP ingress, health route, worker tick, in-memory provider adapters, and deployment plan validation |
-| Hosted staging deployment planner | Provider binding, staging release-gate evidence, Node/container deployment composition, and GitHub App promotion gating |
-| Hosted staging harness | File-backed webhook replay, queue/report/Check Run artifacts, worker cleanup verification, and local release-gate evidence fixtures |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; Worker health and Check Run publisher configuration are live, but end-to-end GitHub App webhook delivery is still blocked pending private App settings verification |
-| Hosted operations evidence | Recorded in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
-| Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard` with contents read, pull requests read, metadata read, and checks write |
+| Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`; hosted operations evidence is in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
 
 ## Quick Start
@@ -299,7 +294,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.26.1` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.27.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/README.zh-CN.md

@@ -1,15 +1,15 @@
 <h1 align="center">ai-saas-guard</h1>
 
 <p align="center">
-  <strong>你用 AI 把 SaaS 做出来了。现在要知道上线前哪里最容易出事。</strong>
+  <strong>你用 AI 把 SaaS 做出来了。现在要在用户发现之前，先找到上线风险。</strong>
 </p>
 
 <p align="center">
-  ai-saas-guard 会优先指出 auth、billing、data access、secrets、MCP 和 deploy 里最值得人工 review 的改动。它本地运行、只读仓库、不上传代码。
+  ai-saas-guard 是面向 AI 构建的 SaaS 的本地优先上线 gate。它会优先指出 auth、billing、data access、secrets、MCP、deploy、CI 和“假成功”路径里最值得人工 review 的改动，让你在上线前知道该先看哪里。它本地运行、只读仓库、不上传代码。
 </p>
 
 <p align="center">
-  它不是渗透测试，而是一份面向上线风险点的实用 review 清单。
+  它不是渗透测试，而是一份证据优先的 review 队列，帮你先看最容易出事的代码。
 </p>
 
 <p align="center">
@@ -28,66 +28,61 @@
 
 ## 它解决什么问题
 
-AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是：它能不能放心给真实用户用。
+AI 能很快把一个 SaaS 做到“看起来能用”。真正危险的是上线后才暴露的信任边界问题：
 
-上线前最危险的通常不是界面小 bug，而是那些会影响用户数据、付费权限、密钥暴露和 AI 工具权限的小改动：
-
-- 一个用户会不会看到另一个客户的数据？
-- Stripe webhook 会不会重复开通权限、漏处理付款失败，或者信任未签名请求？
-- `NEXT_PUBLIC_*` 里是不是不小心暴露了 secret？
-- MCP 工具是不是拿到了 shell、数据库或过宽的文件系统权限？
-- AI 生成的错误处理会不会在真实服务失败后仍然返回“成功”或 demo 数据？
-- Next/Vercel 上线前是不是缺 security headers、env 文档、请求日志或高请求量风险提示？
-- AI 生成的大 PR 里，是不是把 auth、billing 或 deploy 改动藏在 UI 调整中？
+- 一个用户能看到或修改另一个客户的数据
+- Stripe webhook 因为未签名、重复、漏处理失败事件而错误开通权限
+- 真实服务失败后，AI 生成的代码仍然返回“成功”或 demo 数据
+- secret 被 env 配置或 `NEXT_PUBLIC_*` 暴露出去
+- MCP 工具、GitHub workflow 或 deploy job 拿到了过大的权限
+- Next/Vercel 生产环境缺 env 文档、security headers、request ID 或成本风险提示
+- AI 生成的大 PR 把 auth、billing、data、deploy 或测试改动藏在“普通改动”里
 
 `ai-saas-guard` 是面向这个时刻的本地优先、review-first 上线预检工具。它不会证明你的应用绝对安全，也不是渗透测试、认证或完整安全审计。它的目标是给 founder、独立开发者、小团队和 reviewer 一份短而有证据的清单，告诉你上线或合并 PR 前最该先看哪里。
 
 ## 你会得到什么
 
-对仓库或 PR 运行后，它会给出：
+一个命令会返回一份上线前 review 队列：
 
-- 命中的 rule
-- severity 和文件证据
-- 为什么这个问题会影响 SaaS 上线
-- 如何人工验证
-- 实际修复方向
+- terminal 和 Markdown 输出开头会先给出直观上线判断
+- 先看高风险文件，再看 UI 或普通重构
+- 每个 finding 都有 rule ID、severity 和文件证据
+- 说明它为什么会影响 AI 构建的 SaaS 上线
+- 给出可以人工复现的验证步骤
+- 给出实际修复方向，不只是一句泛泛建议
+- 支持 terminal、JSON、SARIF 和 PR markdown，方便本地或 CI 使用
 
-它适合常见 AI 构建的 SaaS 技术栈：
+## 它能帮你抓住哪些问题
 
-- Next.js 和 Vercel
-- Supabase RLS、storage policy、SQL migration
-- Stripe checkout、subscription、webhook
-- Prisma 或 SQL migration
-- MCP server 配置
-- AI 生成的大型混合 PR
+| 上线问题 | ai-saas-guard 会检查什么 |
+| --- | --- |
+| 用户是否只能访问自己的数据？ | Supabase RLS、tenant/owner predicate、storage policy、API ownership 提示、双账号验证建议 |
+| 付费权限是否会正确开通和撤销？ | Stripe webhook 签名、raw body、幂等、entitlement 路径、失败/取消/更新/退款覆盖 |
+| 集成失败时会不会明显失败？ | silent-success fallback、吞错、hardcoded success、production mock/demo data、跳过或占位测试 |
+| 生产环境是否真的等于本地成功？ | Next/Vercel headers、env 文档、public env 盘点、image/request 放大风险、request ID logging |
+| 工具和 CI 权限是不是过大？ | MCP side-effect 分类、本地 policy/receipt 模板、GitHub Actions 权限、concurrency、checkout depth、Action pinning |
+| reviewer 能不能看懂 AI PR？ | `pr-risk` 对 auth、billing、RLS、deploy、API、storage、测试、silent-success、缺 spec context 和大型 diff 排序 |
 
 ## 当前状态
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.26.1`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.26.1`。
+CLI 已发布到 npm：`ai-saas-guard@0.27.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.27.0`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | 已发布为 `ai-saas-guard` |
-| 本地源码运行 | 已可用 |
-| JSON 和 SARIF 输出 | 已可用 |
-| Markdown PR summary | 已可用 |
-| GitHub Action | 已可用 |
-| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.26.1` launch-risk expansion |
-| Action 标签 | `v0.26.1`、`v0` |
+| npm CLI | `ai-saas-guard@0.27.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.27.0` |
+| 输出格式 | Terminal、JSON、SARIF 和 PR markdown |
+| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
+| 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
+| 当前版本 | `0.27.0` CLI 和 hosted Check Run 的 launch-gate report summary |
+| Action 标签 | `v0.27.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
-| 运行时加固 | 单文件和总扫描文本预算、markdown evidence 转义、1 MiB hosted webhook payload 上限、更严格的 hosted deployment 阻断 |
-| Hosted production adapters | GitHub App JWT 签名、installation-token 请求规划、有边界的 worker 执行和终态 cleanup 规划 |
-| Hosted app skeleton | Node/container HTTP ingress、health route、worker tick、in-memory provider adapters 和 deployment plan 校验 |
-| Hosted staging deployment planner | provider binding、staging release-gate evidence、Node/container deployment 组合和 GitHub App promotion gating |
-| Hosted staging harness | 本地 file-backed webhook replay、queue/report/Check Run artifact、worker cleanup 校验和 release-gate evidence fixture |
 | Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；Worker health 和 Check Run publisher 配置已在线，但端到端 GitHub App webhook delivery 仍需要验证私有 App 设置 |
-| Hosted operations evidence | 已记录在 [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
-| Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`，权限为 contents read、pull requests read、metadata read、checks write |
+| Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
 
 ## 快速开始

package/dist/hosted/contracts.js

@@ -479,13 +479,14 @@ export function createHostedCheckRunSummary(input) {
     const totalFindings = getHostedReportFindingTotal(report);
     const localCliCommand = `npx ai-saas-guard@${report.scannerVersion} pr-risk --root .`;
     const conclusion = resolveCheckRunConclusion(report, input.failOnSeverity);
+    const launchGate = hostedLaunchGateVerdict(report);
     return {
         name: CHECK_RUN_NAME,
         conclusion,
         output: {
             title: formatCheckRunTitle(totalFindings, conclusion, input.failOnSeverity),
-            summary: "Review first: verify this launch-readiness signal before release; it is not a full security audit, pentest, or certification.",
-            text: truncateMarkdown(formatCheckRunMarkdown(report, conclusion, localCliCommand), input.maxMarkdownChars)
+            summary: `Launch gate: ${launchGate}. Review first: verify this signal before release; it is not a full security audit, pentest, or certification.`,
+            text: truncateMarkdown(formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate), input.maxMarkdownChars)
         },
         annotations: report.evidence.slice(0, MAX_CHECK_RUN_ANNOTATIONS).map((finding) => {
             const line = finding.line ?? 1;
@@ -1056,6 +1057,22 @@ function getHostedReportFindingTotal(report) {
     const explicitTotal = typeof report.summaryCounts.total === "number" ? report.summaryCounts.total : 0;
     return Math.max(countedBySeverity, explicitTotal, report.evidence.length);
 }
+function hostedLaunchGateVerdict(report) {
+    const summary = report.summaryCounts;
+    if ((summary.critical ?? 0) > 0) {
+        return "blocked";
+    }
+    if ((summary.high ?? 0) > 0) {
+        return "review required";
+    }
+    if ((summary.medium ?? 0) > 0) {
+        return "check before launch";
+    }
+    if ((summary.low ?? 0) > 0 || (summary.info ?? 0) > 0) {
+        return "low-noise review";
+    }
+    return "clear from current heuristics";
+}
 function formatCheckRunTitle(totalFindings, conclusion, failOnSeverity) {
     if (totalFindings === 0) {
         return "AI SaaS Guard found no launch-readiness findings";
@@ -1065,7 +1082,7 @@ function formatCheckRunTitle(totalFindings, conclusion, failOnSeverity) {
     }
     return `AI SaaS Guard found ${totalFindings} finding${totalFindings === 1 ? "" : "s"} to review`;
 }
-function formatCheckRunMarkdown(report, conclusion, localCliCommand) {
+function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate) {
     const categories = getHostedCheckRunCategories(report);
     const filesToReview = getHostedCheckRunFiles(report);
     const findingLines = report.evidence.length === 0
@@ -1080,6 +1097,7 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand) {
         "",
         "Review first: verify findings locally before launch. This hosted check is not a full security audit, pentest, or certification.",
         "",
+        `Launch gate: ${launchGate}`,
         `Conclusion: ${conclusion}`,
         `Local CLI: \`${localCliCommand}\``,
         `Retention: compact report ${report.retentionDays} days; raw source, raw diffs, secrets, and customer payloads are not retained.`,

package/dist/report/launchGate.d.ts

@@ -0,0 +1,4 @@
+import type { BaseReport, Finding } from "../types.js";
+export declare function launchGateVerdict(report: BaseReport): string;
+export declare function reviewFirst(findings: Finding[], limit?: number): string[];
+export declare function manualProofSteps(findings: Finding[], limit?: number): string[];

package/dist/report/launchGate.js

@@ -0,0 +1,36 @@
+export function launchGateVerdict(report) {
+    if (report.summary.critical > 0) {
+        return "blocked: critical launch-readiness findings need review before inviting users";
+    }
+    if (report.summary.high > 0) {
+        return "review required: high-risk launch paths need manual verification before launch";
+    }
+    if (report.summary.medium > 0) {
+        return "check before launch: medium-risk findings should be verified by an owner";
+    }
+    if (report.summary.low > 0 || report.summary.info > 0) {
+        return "low-noise review: confirm these hints against the launch checklist";
+    }
+    return "clear from current heuristics: no findings from this command, not a certification";
+}
+export function reviewFirst(findings, limit = 3) {
+    return findings.slice(0, limit).map((finding) => {
+        const firstEvidence = finding.evidence[0];
+        const location = firstEvidence?.line ? `${firstEvidence.file}:${firstEvidence.line}` : firstEvidence?.file;
+        return `${finding.severity.toUpperCase()} ${finding.ruleId}${location ? ` at ${location}` : ""} - ${finding.title}`;
+    });
+}
+export function manualProofSteps(findings, limit = 3) {
+    const steps = [];
+    const seen = new Set();
+    for (const finding of findings) {
+        const step = finding.suggestedVerification.trim();
+        if (!step || seen.has(step))
+            continue;
+        seen.add(step);
+        steps.push(step);
+        if (steps.length >= limit)
+            break;
+    }
+    return steps;
+}

package/dist/report/markdown.js

@@ -1,3 +1,4 @@
+import { launchGateVerdict, manualProofSteps, reviewFirst } from "./launchGate.js";
 export function formatMarkdownReport(report) {
     if (report.command === "pr-risk")
         return `${formatPrRiskMarkdown(report)}\n`;
@@ -8,6 +9,7 @@ function formatPrRiskMarkdown(report) {
     lines.push("## ai-saas-guard PR risk summary");
     lines.push("");
     lines.push(summaryLine(report));
+    lines.push(`**Launch gate:** ${escapeMarkdownInline(launchGateVerdict(report))}`);
     if (report.categories.length > 0) {
         lines.push("");
         lines.push(`**Risk categories:** ${report.categories.map((category) => `\`${category}\``).join(", ")}`);
@@ -42,6 +44,8 @@ function formatGenericMarkdown(report) {
     lines.push(`## ai-saas-guard ${report.command}`);
     lines.push("");
     lines.push(summaryLine(report));
+    lines.push(`**Launch gate:** ${escapeMarkdownInline(launchGateVerdict(report))}`);
+    appendLaunchQueue(lines, report.findings);
     lines.push("");
     lines.push("### Findings");
     appendFindings(lines, report.findings);
@@ -56,6 +60,16 @@ function appendList(lines, items) {
         lines.push(`- ${item}`);
     }
 }
+function appendLaunchQueue(lines, findings) {
+    if (findings.length === 0)
+        return;
+    lines.push("");
+    lines.push("### Review First");
+    appendList(lines, reviewFirst(findings).map(escapeMarkdownInline));
+    lines.push("");
+    lines.push("### Manual Proof To Run Next");
+    appendList(lines, manualProofSteps(findings).map(escapeMarkdownInline));
+}
 function appendFindings(lines, findings) {
     if (findings.length === 0) {
         lines.push("");

package/dist/report/terminal.js

@@ -1,14 +1,26 @@
+import { launchGateVerdict, manualProofSteps, reviewFirst } from "./launchGate.js";
 export function formatTerminalReport(report) {
     const lines = [];
     lines.push(`ai-saas-guard ${report.command}`);
     lines.push(`Root: ${report.rootDir}`);
     lines.push(`Findings: ${report.summary.total} total | critical ${report.summary.critical} | high ${report.summary.high} | medium ${report.summary.medium} | low ${report.summary.low} | info ${report.summary.info}`);
+    lines.push(`Launch gate: ${launchGateVerdict(report)}`);
     if (report.findings.length === 0) {
         lines.push("");
         lines.push("No heuristic launch-readiness risks found by this command.");
         appendCommandExtras(lines, report);
         return lines.join("\n");
     }
+    lines.push("");
+    lines.push("Review first:");
+    for (const item of reviewFirst(report.findings)) {
+        lines.push(`- ${item}`);
+    }
+    lines.push("");
+    lines.push("Manual proof to run next:");
+    for (const step of manualProofSteps(report.findings)) {
+        lines.push(`- ${step}`);
+    }
     for (const [index, item] of report.findings.entries()) {
         lines.push("");
         lines.push(`${index + 1}. [${item.severity.toUpperCase()}] ${item.title}`);

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.26.1` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.27.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.26.1`
+- Current published version: `0.27.0`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.26.1`
+- GitHub Release: `v0.27.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.26.1`.
+1. Create and review a release tag such as `v0.27.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -160,7 +160,7 @@ OpenSSF Best Practices:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current published release line: `v0.26.1`
+- Current published release line: `v0.27.0`
 - Next source candidate: none
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`

package/docs/repository-trust-hardening.md

@@ -40,6 +40,8 @@ It covers:
 
 The schedule is weekly with cooldown windows and a small open pull request limit. This keeps update noise low while still surfacing security and maintenance updates.
 
+The npm update policy ignores semver-major `@types/node` bumps while the package supports Node.js 20. This avoids accidentally type-checking against newer Node-only APIs that the published CLI does not promise to support.
+
 Dependabot security updates and vulnerability alerts are enabled in repository settings.
 
 ## CodeQL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -87,6 +87,6 @@
   "devDependencies": {
     "@types/node": "^20",
     "fast-check": "^4.8.0",
-    "typescript": "^5"
+    "typescript": "^6"
   }
 }