ai-saas-guard 0.35.1 → 0.36.0

package/README.md

@@ -146,7 +146,7 @@ One command returns a launch-readiness report with:
 - why the finding matters for an AI-built SaaS launch
 - manual verification steps you can actually run
 - practical fix direction, not generic advice
-- short `--summary`, terminal, JSON, SARIF, and PR markdown output for local review or CI
+- launch decision queue, ranking explanation, trust statement, short `--summary`, terminal, JSON, SARIF, and PR markdown output for local review or CI
 
 ## Problems It Helps You Catch
 
@@ -231,13 +231,13 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.35.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.35.1` |
-| Outputs | Short summary, terminal, JSON, SARIF, and PR-focused markdown |
+| npm CLI | `ai-saas-guard@0.36.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.36.0` |
+| Outputs | Launch decision queue, short summary, 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.35.1`, `v0` |
-| Current release | `0.35.1` updates the case-study fixture to a patched Next.js release so GitHub Dependabot no longer reports known Next.js advisories for the packaged example |
+| Versioned Action tags | `v0.36.0`, `v0` |
+| Current release | `0.36.0` turns Markdown and summary output into a clearer launch decision queue with ranking explanations, reviewer checklists, case-study flow, and local trust/resource statements |
 | 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 |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
@@ -297,7 +297,7 @@ AI-generated PRs often combine unrelated work:
 - suggested PR split
 - required tests or manual verification
 - explicit git-diff diagnostics when a base ref or shallow checkout prevents PR classification
-- PR-focused markdown for GitHub step summaries or PR comments
+- PR-focused markdown with launch decision queue, reviewer checklist, ranking explanation, and suggested split for GitHub step summaries or PR comments
 
 ```bash
 node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
@@ -415,7 +415,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.35.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.36.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/report/launchGate.d.ts

@@ -1,5 +1,9 @@
 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 launchDecisionQuestions(findings: Finding[]): string[];
+export declare function rankingExplanation(findings: Finding[]): string[];
+export declare function prReviewerChecklist(): string[];
+export declare function trustStatement(): string[];
 export declare function manualProofSteps(findings: Finding[], limit?: number): string[];
 export declare function nextSteps(findings: Finding[]): string[];

package/dist/report/launchGate.js

@@ -20,6 +20,47 @@ export function reviewFirst(findings, limit = 3) {
         return `${finding.severity.toUpperCase()} ${finding.ruleId}${location ? ` at ${location}` : ""} - ${finding.title}`;
     });
 }
+export function launchDecisionQuestions(findings) {
+    if (findings.length === 0) {
+        return [
+            "Can a real user get access they should not have? No current finding, but still run a two-account auth/data-access smoke.",
+            "Can the app claim success when something failed? No current finding, but still force one provider failure before launch.",
+            "Can launch infrastructure do too much damage? No current finding, but still confirm env, CI, MCP, and deploy permissions."
+        ];
+    }
+    return [
+        "Can a real user get access they should not have? Review auth, tenant ownership, Supabase RLS, webhook entitlement, and data mutation findings first.",
+        "Can the app claim success when something failed? Review silent-success, hardcoded fallback, skipped test, and provider failure findings before launch.",
+        "Can launch infrastructure do too much damage? Review env exposure, GitHub Actions permissions, MCP tool power, deploy config, logging, and resource hints."
+    ];
+}
+export function rankingExplanation(findings) {
+    if (findings.length === 0) {
+        return [
+            "No findings were ranked by this command; this is still a heuristic result, not a certification."
+        ];
+    }
+    return [
+        "ai-saas-guard ranks auth, billing, tenant data, RLS, webhooks, and silent-success findings before deploy/cost hygiene because those paths can grant access, expose customer data, or hide production failures.",
+        "Medium and low deploy, CI, MCP, and observability findings stay in the queue because they can amplify launch damage, but they should not distract from critical user-access, payment, and data-access proof."
+    ];
+}
+export function prReviewerChecklist() {
+    return [
+        "What changed at the trust boundary?",
+        "Why this auth/session/payment/data access decision?",
+        "What manual proof should block merge until it passes?",
+        "Which files should be reviewed together before this PR is approved?",
+        "Should auth, billing, data access, deploy, or UI changes be split into separate PRs?"
+    ];
+}
+export function trustStatement() {
+    return [
+        "Runs as a local-first, deterministic, read-only launch gate over repository files.",
+        "Does not upload code or call an LLM.",
+        "Uses bounded file collection and ignores heavy generated directories such as node_modules, .next, dist, build, coverage, and .git."
+    ];
+}
 export function manualProofSteps(findings, limit = 3) {
     const steps = [];
     const seen = new Set();

package/dist/report/markdown.js

@@ -1,4 +1,4 @@
-import { launchGateVerdict, manualProofSteps, nextSteps, reviewFirst } from "./launchGate.js";
+import { launchDecisionQuestions, launchGateVerdict, manualProofSteps, nextSteps, prReviewerChecklist, rankingExplanation, reviewFirst, trustStatement } from "./launchGate.js";
 export function formatMarkdownReport(report) {
     if (report.command === "demo")
         return `${formatDemoMarkdown(report)}\n`;
@@ -48,6 +48,9 @@ function formatPrRiskMarkdown(report) {
         lines.push(`**Risk categories:** ${report.categories.map((category) => `\`${category}\``).join(", ")}`);
     }
     lines.push("");
+    lines.push("### Launch Decision Queue");
+    appendList(lines, launchDecisionQuestions(report.findings).map(escapeMarkdownInline));
+    lines.push("");
     lines.push("### Review first");
     if (report.topRiskyFiles.length === 0) {
         lines.push("");
@@ -65,6 +68,15 @@ function formatPrRiskMarkdown(report) {
     lines.push("### Required verification");
     appendList(lines, report.requiredTests.length > 0 ? report.requiredTests : report.reviewChecklist);
     lines.push("");
+    lines.push("### Reviewer checklist");
+    appendList(lines, prReviewerChecklist().map(escapeMarkdownInline));
+    lines.push("");
+    lines.push("### Why this review order");
+    appendList(lines, [
+        "Rank trust-boundary files before cosmetic files because auth, billing, tenant data, RLS, webhook, and silent-success changes can affect real users before UI issues do.",
+        ...rankingExplanation(report.findings)
+    ].map(escapeMarkdownInline));
+    lines.push("");
     lines.push("### Suggested PR split");
     appendList(lines, report.suggestedSplit.length > 0 ? report.suggestedSplit : ["No split suggestion from the current diff."]);
     lines.push("");
@@ -94,6 +106,15 @@ function appendList(lines, items) {
     }
 }
 function appendLaunchQueue(lines, findings) {
+    lines.push("");
+    lines.push("### Launch Decision Queue");
+    appendList(lines, launchDecisionQuestions(findings).map(escapeMarkdownInline));
+    lines.push("");
+    lines.push("### Why This Is Ranked First");
+    appendList(lines, rankingExplanation(findings).map(escapeMarkdownInline));
+    lines.push("");
+    lines.push("### Trust Statement");
+    appendList(lines, trustStatement().map(escapeMarkdownInline));
     if (findings.length === 0)
         return;
     lines.push("");

package/dist/report/summary.js

@@ -1,4 +1,4 @@
-import { launchGateVerdict, manualProofSteps, nextSteps, reviewFirst } from "./launchGate.js";
+import { launchDecisionQuestions, launchGateVerdict, manualProofSteps, nextSteps, reviewFirst } from "./launchGate.js";
 export function formatSummaryReport(report) {
     if (report.command === "demo")
         return formatShowcaseSummary(report);
@@ -7,6 +7,10 @@ export function formatSummaryReport(report) {
     lines.push(`Root: ${report.rootDir}`);
     lines.push(`Findings: ${summaryText(report)}`);
     lines.push(`Launch gate: ${launchGateVerdict(report)}`);
+    lines.push(`Decision queue: ${launchDecisionQuestions(report.findings)[0]}`);
+    if (report.findings.length > 0) {
+        lines.push("Review trust-boundary findings before deploy/cost hygiene.");
+    }
     if (report.findings.length === 0) {
         lines.push("");
         lines.push("No heuristic launch-readiness risks found by this command.");

package/docs/README.zh-CN.md

@@ -143,7 +143,7 @@ Next steps
 - 说明它为什么会影响 AI 构建的 SaaS 上线
 - 给出可以人工复现的验证步骤
 - 给出实际修复方向，不只是一句泛泛建议
-- 支持短 `--summary`、terminal、JSON、SARIF 和 PR markdown，方便本地或 CI 使用
+- 支持上线决策队列、排序解释、trust statement、短 `--summary`、terminal、JSON、SARIF 和 PR markdown，方便本地或 CI 使用
 
 ## 它能帮你抓住哪些问题
 
@@ -211,18 +211,18 @@ node dist/cli.js scan --root /path/to/your-saas
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.35.1`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.35.1`。
+CLI 已发布到 npm：`ai-saas-guard@0.36.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.36.0`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.35.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.35.1` |
-| 输出格式 | 短 summary、Terminal、JSON、SARIF 和 PR markdown |
+| npm CLI | `ai-saas-guard@0.36.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.36.0` |
+| 输出格式 | 上线决策队列、短 summary、Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.35.1` 将 case-study fixture 升级到已修补的 Next.js 版本，避免 GitHub Dependabot 对包内示例继续报告已知 Next.js advisories |
-| Action 标签 | `v0.35.1`、`v0` |
+| 当前版本 | `0.36.0` 将 Markdown 和 summary 输出升级成更清楚的上线决策队列，加入排序解释、reviewer checklist、case-study flow 和本地 trust/resource statement |
+| Action 标签 | `v0.36.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 |
 | Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；签名 GitHub App webhook delivery 和 compact Check Run staging smoke 已通过 |

package/docs/case-study-ai-saas.md

@@ -14,8 +14,46 @@ Expected findings include:
 
 Use it locally:
 
+## Local Scan
+
 ```bash
 npx ai-saas-guard@latest scan --root examples/case-study-ai-saas --summary
 ```
 
+## Markdown Report
+
+Use Markdown when you want a launch decision queue that can be pasted into an issue or PR:
+
+```bash
+npx ai-saas-guard@latest scan --root examples/case-study-ai-saas --markdown
+```
+
+The report should start with the launch gate, decision queue, top risks, manual proof steps, ranking explanation, and trust statement before listing every finding.
+
+## PR Risk
+
+To see how the same middle-layer logic works for an AI-heavy PR, run:
+
+```bash
+npx ai-saas-guard@latest pr-risk --root examples/case-study-ai-saas --base origin/main --markdown
+```
+
+The PR report is designed for reviewers: review order, required verification, reviewer checklist, suggested PR split, and file evidence.
+
+## Fix-before/fix-after
+
+Use this fixture as the "before" state. The expected fix path is not to make the fixture a starter template; it is to demonstrate how a reviewer would close the launch gate:
+
+- verify Stripe signatures before entitlement updates
+- replace fake success fallbacks with explicit error or degraded-mode handling
+- scope Supabase RLS by tenant/user ownership
+- add Next/Vercel security headers and request IDs
+- reduce GitHub Actions permissions and add PR concurrency cancellation
+
+After each fix, rerun the local scan and keep the manual proof result with the launch checklist.
+
+## Trust and Resource Boundary
+
+The fixture is scanned locally. `ai-saas-guard` does not upload source code or call an LLM, and normal CLI scans use bounded file collection with generated and dependency directories ignored.
+
 This fixture is public-safe and synthetic. It is not a SaaS starter template, pentest target, certification artifact, or full audit.

package/docs/github-action.md

@@ -8,7 +8,7 @@ The Action runs the same local scanner inside the GitHub-hosted runner. It reads
 
 ## PR Summary
 
-Use markdown when reviewers need a short, evidence-first summary of risky files, required verification, and suggested PR split.
+Use markdown when reviewers need a short, evidence-first launch decision queue: risky files, required verification, reviewer checklist, ranking explanation, and suggested PR split.
 
 ```yaml
 name: ai-saas-guard-pr-summary
@@ -37,7 +37,7 @@ jobs:
       - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
 ```
 
-Use markdown for PR review triage. It is intentionally short enough for a GitHub step summary or a PR comment created by your own workflow. It does not require a hosted service.
+Use markdown for PR review triage. It is intentionally short enough for a GitHub step summary or a PR comment created by your own workflow. It does not require a hosted service. The report keeps the middle-layer contract explicit: it translates trust-boundary changes into human review questions, not an automatic approval.
 
 ## Project Config
 
@@ -98,4 +98,4 @@ jobs:
           sarif_file: ai-saas-guard.sarif
 ```
 
-Use SARIF for tracking alerts over time. Use markdown for reviewer guidance on a specific PR. Many teams should run both: markdown for quick review order, SARIF for code scanning visibility.
+Use SARIF for tracking alerts over time. Use markdown for reviewer guidance on a specific PR. Many teams should run both: markdown for launch decision queues, SARIF for code scanning visibility.

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.35.1`
+- Current published version: `0.36.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.35.1`
+- GitHub Release: `v0.36.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.35.1`.
+1. Create and review a release tag such as `v0.36.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/positioning.md

@@ -2,6 +2,32 @@
 
 This project should compete by being narrow, trustworthy, and review-oriented.
 
+## North Star
+
+`ai-saas-guard` should become the launch-risk middle layer between AI-generated SaaS code and real users.
+
+The product is not trying to be the lowest-level static-analysis engine, and it is not trying to be a top-level full security audit service. Its job is to translate messy AI-built SaaS code and AI-heavy PRs into a founder-readable, reviewer-ready launch gate:
+
+```text
+AI-built SaaS code
+        ↓
+ai-saas-guard: launch-risk middle layer
+        ↓
+founder, reviewer, CI, or GitHub App makes the final launch decision
+```
+
+The long-term product sentence:
+
+> The launch gate between AI-generated code and real users.
+
+Every major feature should support this middle-layer role:
+
+- translate code changes into launch-risk language
+- prioritize trust-boundary paths: auth, billing, tenant data, RLS, webhooks, env, CI, MCP, and deploy
+- turn findings into manual proof steps a human can actually run
+- keep the default trust model local-first, deterministic, read-only, no code upload, and no LLM calls
+- avoid claiming pentest, certification, full audit, or complete vulnerability discovery
+
 ## Public Position
 
 `ai-saas-guard` is a local-first launch preflight for AI-built SaaS apps. It finds common production-readiness risks and produces concrete verification steps.

package/docs/project-handoff.md

@@ -23,6 +23,8 @@ Recent setup commits at the time this handoff was created:
 
 `ai-saas-guard` is a local-first launch preflight CLI for AI-built SaaS apps.
 
+North star: `ai-saas-guard` is the launch-risk middle layer between AI-generated SaaS code and real users. It translates AI-built SaaS code and AI-heavy PRs into a founder-readable, reviewer-ready launch gate. It is not a low-level static-analysis engine, a pentest, a certification, or a full security audit service.
+
 The core user is a founder, solo builder, or reviewer shipping an AI-assisted SaaS MVP who needs to know what deserves human review before launch or merge.
 
 The narrow product promise:

package/docs/sample-launch-report.md

@@ -6,6 +6,8 @@ This is a synthetic, public-safe example of the kind of review queue `ai-saas-gu
 ai-saas-guard scan summary
 Findings: 6 findings: 0 critical, 3 high, 3 medium, 0 low, 0 info
 Launch gate: review required: high-risk launch paths need manual verification before launch
+Decision queue: Can a real user get access they should not have? Review auth, tenant ownership, Supabase RLS, webhook entitlement, and data mutation findings first.
+Review trust-boundary findings before deploy/cost hygiene.
 
 Top risks:
 - HIGH stripe.webhook.missing-signature at app/api/stripe/webhook/route.ts:12 - Stripe webhook does not verify the Stripe signature
@@ -25,6 +27,12 @@ Full report:
   Rerun without --summary, or use --json, --sarif, or --markdown where supported.
 ```
 
+Markdown reports include the same decision queue plus:
+
+- why auth, billing, tenant data, RLS, webhooks, and silent-success findings rank first
+- a trust statement: local-first, deterministic, read-only, no code upload, no LLM calls
+- a reviewer checklist for PR risk output
+
 The full terminal report expands each finding:
 
 ```text
@@ -86,4 +94,4 @@ Start with the highest severity findings that touch trust-boundary code: auth, b
 - Why could this fail for real users?
 - What manual proof shows the path fails closed?
 
-The report is a focused review queue. It does not replace your two-account authorization tests, Stripe webhook replay, deploy-preview checks, or human review.
+The report is a focused launch decision queue. It does not replace your two-account authorization tests, Stripe webhook replay, deploy-preview checks, or human review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "Local-first CLI that catches launch blockers in AI-built Next.js/Supabase/Stripe SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",