ai-saas-guard 0.5.0 → 0.7.0

package/README.md

@@ -51,8 +51,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | 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.5.0`, `v0` |
-| npm package | `ai-saas-guard@0.5.0` |
+| Versioned Action tags | `v0.7.0`, `v0` |
+| npm package | `ai-saas-guard@0.7.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -170,6 +170,10 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
 | `check-mcp` | Inventory MCP configs and classify side effects |
 
+## Launch Readiness Checklist
+
+Use [docs/launch-readiness-checklist.md](docs/launch-readiness-checklist.md) when an app is close to inviting real users. It explains how to combine `ai-saas-guard` output with manual two-account authorization testing, Stripe webhook verification, MCP config review, Supabase policy review, deploy checks, rollback planning, and a clear reminder that this is not a full security audit.
+
 ## Stripe Webhook Replay
 
 Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-stripe` flags missing signature verification, idempotency, lifecycle handlers, or entitlement updates. The cookbook maps findings to concrete `stripe listen` and `stripe trigger` commands for checkout success, failed renewal, subscription update, cancellation, refund, duplicate delivery, and out-of-order event review.
@@ -185,17 +189,26 @@ Add `.ai-saas-guard.json` at the repository root to tune findings without changi
     "stripe.webhook.missing-signature": "off",
     "stripe.webhook.missing-idempotency": "critical",
     "deploy.env.example-missing": "info"
-  }
+  },
+  "suppressions": [
+    {
+      "ruleId": "stripe.webhook.missing-idempotency",
+      "paths": ["app/api/stripe/webhook/route.ts"],
+      "reason": "Temporary launch exception with duplicate-event coverage in integration tests."
+    }
+  ]
 }
 ```
 
 `rules` is keyed by published rule ID from [docs/rules.md](docs/rules.md). Set a rule to `off` to remove matching findings from terminal, JSON, SARIF, and markdown output. Set a rule to `critical`, `high`, `medium`, `low`, or `info` to override severity before summaries and `--fail-on` are evaluated.
 
+Use `suppressions` for narrower false-positive handling when one rule is noisy only for specific generated files, fixtures, or reviewed exceptions. Each suppression must name a known `ruleId` and one or more relative `paths` globs, such as `generated/**` or `app/api/stripe/webhook/route.ts`.
+
 `failOn` sets the default CI failure threshold for the project. A CLI `--fail-on` value takes precedence, so local runs can still use `--fail-on none` or a stricter threshold.
 
 ## 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.5.0` 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.7.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -324,8 +337,6 @@ Open-source core:
 
 Near-term priorities:
 
-- launch-readiness checklist content
-- false-positive suppression and rule stability labels
 - GitHub App design note for the potential hosted layer
 
 Potential paid layer later:

package/dist/config.d.ts

@@ -1,10 +1,16 @@
 import type { BaseReport, Severity } from "./types.js";
 export declare const defaultConfigFileName = ".ai-saas-guard.json";
 export type RuleConfigValue = "off" | Severity;
+export interface FindingSuppression {
+    ruleId: string;
+    paths: string[];
+    reason?: string;
+}
 export interface GuardConfig {
     sourcePath?: string;
     failOn?: Severity | "none";
     rules: Record<string, RuleConfigValue>;
+    suppressions?: FindingSuppression[];
 }
 export declare function loadGuardConfig(rootDir: string, explicitPath?: string): Promise<GuardConfig>;
 export declare function applyGuardConfig<T extends BaseReport>(report: T, config: GuardConfig): T;

package/dist/config.js

@@ -11,22 +11,22 @@ export async function loadGuardConfig(rootDir, explicitPath) {
     }
     catch (error) {
         if (!explicitPath && isNotFoundError(error))
-            return { rules: {} };
+            return { rules: {}, suppressions: [] };
         throw new Error(`Could not read config file ${sourcePath}: ${errorMessage(error)}`);
     }
     return parseGuardConfig(content, sourcePath);
 }
 export function applyGuardConfig(report, config) {
     const configuredRuleIds = Object.keys(config.rules);
-    if (configuredRuleIds.length === 0)
+    const suppressions = config.suppressions ?? [];
+    if (configuredRuleIds.length === 0 && suppressions.length === 0)
         return report;
     const findings = sortFindings(report.findings.flatMap((finding) => {
         const ruleConfig = config.rules[finding.ruleId];
-        if (!ruleConfig)
-            return [finding];
         if (ruleConfig === "off")
             return [];
-        return [{ ...finding, severity: ruleConfig }];
+        const configuredFinding = ruleConfig ? { ...finding, severity: ruleConfig } : finding;
+        return isSuppressed(configuredFinding, suppressions) ? [] : [configuredFinding];
     }));
     return {
         ...report,
@@ -63,12 +63,84 @@ function parseGuardConfig(content, sourcePath) {
         }
         rules[ruleId] = value;
     }
+    const rawSuppressions = parsed.suppressions ?? [];
+    if (!Array.isArray(rawSuppressions)) {
+        throw new Error("Invalid config suppressions: expected an array");
+    }
+    const suppressions = rawSuppressions.map((value, index) => parseSuppression(value, index));
     return {
         sourcePath,
         failOn,
-        rules
+        rules,
+        suppressions
+    };
+}
+function parseSuppression(value, index) {
+    if (!isPlainObject(value)) {
+        throw new Error(`Invalid config suppressions[${index}]: expected an object`);
+    }
+    const ruleId = value.ruleId;
+    if (typeof ruleId !== "string" || ruleId.length === 0) {
+        throw new Error(`Invalid config suppressions[${index}].ruleId: expected a rule ID`);
+    }
+    if (!getRuleMetadata(ruleId)) {
+        throw new Error(`Unknown rule ID in suppression: ${ruleId}`);
+    }
+    const paths = value.paths;
+    if (!Array.isArray(paths) || paths.length === 0 || !paths.every((path) => typeof path === "string" && path.length > 0)) {
+        throw new Error(`Invalid config suppressions[${index}].paths: expected a non-empty array of path globs`);
+    }
+    const reason = value.reason;
+    if (reason !== undefined && typeof reason !== "string") {
+        throw new Error(`Invalid config suppressions[${index}].reason: expected a string`);
+    }
+    return {
+        ruleId,
+        paths,
+        reason
     };
 }
+function isSuppressed(finding, suppressions) {
+    return suppressions.some((suppression) => suppression.ruleId === finding.ruleId &&
+        finding.evidence.some((evidence) => suppression.paths.some((pattern) => pathMatches(pattern, evidence.file))));
+}
+function pathMatches(pattern, filePath) {
+    return globToRegExp(normalizeConfigPath(pattern)).test(normalizeConfigPath(filePath));
+}
+function normalizeConfigPath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function globToRegExp(pattern) {
+    let expression = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === "*") {
+            const next = pattern[index + 1];
+            const afterNext = pattern[index + 2];
+            if (next === "*" && afterNext === "/") {
+                expression += "(?:.*/)?";
+                index += 2;
+            }
+            else if (next === "*") {
+                expression += ".*";
+                index += 1;
+            }
+            else {
+                expression += "[^/]*";
+            }
+        }
+        else if (char === "?") {
+            expression += "[^/]";
+        }
+        else {
+            expression += escapeRegExp(char);
+        }
+    }
+    return new RegExp(`${expression}$`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
 function isRuleConfigValue(value) {
     return value === "off" || isSeverity(value);
 }

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";
 export type { BaseReport, CommandName, Evidence, Finding, McpReport, McpServerInventory, PrRiskFile, PrRiskReport, ScanOptions, StripeReport, SupabaseReport } from "./types.js";
 export type { ScanContext, ScanInput } from "./context.js";
-export type { GuardConfig, RuleConfigValue } from "./config.js";
+export type { FindingSuppression, GuardConfig, RuleConfigValue } from "./config.js";
 export type { RuleMetadata, RuleStability } from "./rules/catalog.js";

package/dist/report/sarif.js

@@ -5,13 +5,18 @@ export function formatSarifReport(report) {
         if (rules.has(finding.ruleId))
             continue;
         const metadata = getRuleMetadata(finding.ruleId);
+        const stability = metadata?.stability ?? "default";
         rules.set(finding.ruleId, {
             id: finding.ruleId,
             name: finding.ruleId,
             shortDescription: { text: metadata?.title ?? finding.title },
             fullDescription: { text: metadata?.why ?? finding.why },
             help: { text: `${finding.suggestedVerification}\n\nFix direction: ${finding.suggestedFix}` },
-            defaultConfiguration: { level: sarifLevel(finding) }
+            defaultConfiguration: { level: sarifLevel(finding) },
+            properties: {
+                "ai-saas-guard/stability": stability,
+                tags: [`stability:${stability}`]
+            }
         });
     }
     return `${JSON.stringify({

package/dist/rules/catalog.js

@@ -4,14 +4,14 @@ export const RULE_CATALOG = {
         severity: "high",
         title: "Secret-like value detected",
         why: "Credentials committed to source, config, or examples can be exposed before launch.",
-        stability: "default"
+        stability: "strict"
     },
     "next.env.public-secret": {
         ruleId: "next.env.public-secret",
         severity: "high",
         title: "Risky NEXT_PUBLIC environment variable",
         why: "Next.js exposes NEXT_PUBLIC variables to browser code, so secret-like values can leak to users.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.missing-route": {
         ruleId: "stripe.webhook.missing-route",
@@ -25,7 +25,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Stripe webhook does not verify the Stripe signature",
         why: "Unsigned webhook handlers can accept forged billing events.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.raw-body-risk": {
         ruleId: "stripe.webhook.raw-body-risk",
@@ -39,7 +39,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Stripe signing secret appears public",
         why: "Public Stripe secrets can be bundled into client code and abused.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.missing-idempotency": {
         ruleId: "stripe.webhook.missing-idempotency",
@@ -53,7 +53,7 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Stripe webhook does not show an entitlement update path",
         why: "Returning HTTP 200 is not the same as changing application access state.",
-        stability: "default"
+        stability: "experimental"
     },
     "stripe.webhook.missing-critical-event": {
         ruleId: "stripe.webhook.missing-critical-event",
@@ -67,7 +67,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Broad Supabase RLS policy",
         why: "`USING (true)` or `WITH CHECK (true)` can turn login into broad data access or writes.",
-        stability: "default"
+        stability: "strict"
     },
     "supabase.rls.missing-ownership-filter": {
         ruleId: "supabase.rls.missing-ownership-filter",
@@ -95,7 +95,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Sensitive table does not enable row level security",
         why: "User-data tables should enable row level security.",
-        stability: "default"
+        stability: "strict"
     },
     "supabase.storage.public-bucket": {
         ruleId: "supabase.storage.public-bucket",
@@ -109,14 +109,14 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Sensitive API route lacks obvious rate limiting",
         why: "Login, checkout, upload, AI, and webhook routes are common abuse targets.",
-        stability: "default"
+        stability: "experimental"
     },
     "api.route.auth-without-ownership": {
         ruleId: "api.route.auth-without-ownership",
         severity: "high",
         title: "API route checks auth but lacks an ownership guard",
         why: "Login checks do not prove resource ownership checks.",
-        stability: "default"
+        stability: "experimental"
     },
     "deploy.next.static-export-api-risk": {
         ruleId: "deploy.next.static-export-api-risk",
@@ -137,14 +137,14 @@ export const RULE_CATALOG = {
         severity: "low",
         title: "Important runtime env var is not documented",
         why: "Missing env docs cause local-success, production-failure deploys.",
-        stability: "default"
+        stability: "experimental"
     },
     "mcp.config.invalid-json": {
         ruleId: "mcp.config.invalid-json",
         severity: "medium",
         title: "MCP config is not valid JSON",
         why: "Broken MCP configs hide the actual tool inventory.",
-        stability: "default"
+        stability: "strict"
     },
     "mcp.config.plaintext-secret": {
         ruleId: "mcp.config.plaintext-secret",
@@ -200,7 +200,7 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Review first sensitive PR surface",
         why: "AI-generated PRs often bury trust-boundary changes inside larger diffs.",
-        stability: "default"
+        stability: "experimental"
     },
     "pr-risk.diff-unavailable": {
         ruleId: "pr-risk.diff-unavailable",

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.5.0` 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.7.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 
@@ -50,7 +50,7 @@ The Action auto-loads `.ai-saas-guard.json` from `root` when the file exists. Us
           fail-on: none
 ```
 
-Project config can disable noisy rules, override severity by rule ID, and set a default `failOn` threshold. A workflow `fail-on` input overrides the config threshold for that run.
+Project config can disable noisy rules, override severity by rule ID, apply path-specific `suppressions`, and set a default `failOn` threshold. A workflow `fail-on` input overrides the config threshold for that run.
 
 ## SARIF Upload
 

package/docs/launch-readiness-checklist.md

@@ -0,0 +1,191 @@
+# Launch Readiness Checklist
+
+Use this checklist when an AI-built SaaS app is close to launch, a founder is about to invite real users, or a reviewer needs a practical pre-merge review path.
+
+This is not a full security audit, penetration test, compliance review, or proof that the app is secure. It is a founder-readable launch preflight that combines `ai-saas-guard` findings with manual verification for the most common SaaS launch blockers.
+
+## Start With The Local Preflight
+
+Run from the app repository:
+
+```bash
+npx ai-saas-guard@latest scan --root .
+npx ai-saas-guard@latest pr-risk --root . --base origin/main
+npx ai-saas-guard@latest check-supabase --root .
+npx ai-saas-guard@latest check-stripe --root .
+npx ai-saas-guard@latest check-mcp --root .
+```
+
+Treat every finding as a review queue item. The tool is read-only and local-first, so it can show where to inspect, but it cannot confirm production settings, account ownership, live Stripe dashboard state, or every possible authorization path.
+
+## Launch Blocker Rules
+
+Use these labels while reviewing:
+
+| Level | Meaning | Examples |
+| --- | --- | --- |
+| Launch blocker | Do not ship until fixed or explicitly disabled for the product. | Any user can read another tenant's data, unsigned Stripe webhooks grant access, real secrets are committed. |
+| Must verify | Shipping may be reasonable only after a named manual test passes. | Rate limits, billing lifecycle handling, storage object scope, rollback path. |
+| Follow-up | Track after launch when the current product risk is bounded. | Extra docs, sharper false-positive suppression, non-critical workflow polish. |
+
+If a finding affects auth, billing, user data, secrets, file storage, production deploy config, or MCP tools with side effects, assume it is at least "must verify" until a human has tested the exact path.
+
+## Two-Account Authorization Testing
+
+Two-account authorization testing is the fastest manual check for broken SaaS isolation.
+
+Prepare two ordinary test accounts:
+
+- User A in organization or workspace A.
+- User B in organization or workspace B.
+- At least one private object owned by each account or workspace: project, document, invoice, file, message, API key, or team member.
+
+Verify read isolation:
+
+- Log in as User A and open User A's private objects.
+- Try to load User B's object by changing route parameters, object IDs, slugs, search filters, API URLs, and browser history entries.
+- Repeat the same checks through direct API calls if the app exposes JSON routes.
+- Confirm User A receives a 403 or 404 and no object metadata leaks in the response.
+
+Verify write isolation:
+
+- As User A, try to update, delete, invite users to, export, or share User B's objects by tampering with IDs.
+- Confirm the server rejects the request, not only the UI.
+- Confirm no partial write, audit entry, billing change, storage object, notification, or background job was created.
+
+Verify tenant switching:
+
+- If a user can belong to multiple workspaces, switch active workspaces and repeat the same read/write checks.
+- Confirm server-side ownership checks use the selected tenant membership, not only a client-side workspace ID.
+
+For Supabase apps, compare these manual checks with row-level security policy evidence from `check-supabase`. RLS should protect sensitive tables even when a route, query builder, or generated client code is wrong.
+
+## Stripe Webhook Verification
+
+Stripe webhook verification is required for subscription or credit products because checkout redirects are not billing truth.
+
+Minimum checks:
+
+- The webhook route reads the raw request body.
+- The handler verifies the `Stripe-Signature` header with the server-only webhook secret before any database write.
+- The signing secret is never exposed through `NEXT_PUBLIC_*`, client bundles, public logs, issue comments, or screenshots.
+- The handler stores or dedupes `event.id`.
+- Entitlement state is updated from Stripe webhook reconciliation, not only from checkout success pages.
+
+Replay the critical billing paths with the companion cookbook:
+
+```bash
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+stripe trigger checkout.session.completed
+stripe trigger invoice.payment_failed
+stripe trigger customer.subscription.updated
+stripe trigger customer.subscription.deleted
+stripe trigger charge.refunded
+```
+
+Expected evidence:
+
+- Checkout success grants the right user or tenant access only after signature verification.
+- Failed invoice creates the intended past-due or grace state.
+- Subscription updates reconcile plan, quantity, status, cancellation, and period fields.
+- Cancellation revokes or downgrades paid access.
+- Refund handling is explicit, even if the product requires manual review.
+- Duplicate delivery of the same event ID is a no-op.
+- Out-of-order events reconcile to one durable entitlement state.
+
+See [stripe-webhook-replay.md](stripe-webhook-replay.md) for the full command cookbook.
+
+## MCP Config Review
+
+MCP config review matters because local tools can turn prompt injection into filesystem, shell, database, or network side effects.
+
+Inventory every MCP server used by the app, agent, or development workflow:
+
+- Config files such as `.mcp.json`, `.cursor/mcp.json`, `claude_desktop_config.json`, or tool-specific equivalents.
+- Tool descriptions that expose shell commands, raw SQL, browser automation, filesystem writes, or deployment actions.
+- Environment variables and credentials passed to MCP servers.
+- Bind addresses and transport URLs.
+
+Review questions:
+
+- Does any MCP server bind to `0.0.0.0` or a non-localhost host?
+- Does any tool allow broad filesystem read/write access outside the intended repository?
+- Does any tool run arbitrary shell commands or raw SQL against production-like data?
+- Are credentials stored in plaintext config files?
+- Are secret-bearing config files group-readable or world-readable?
+- Can the tool mutate billing, user access, customer data, or deploy state without a human approval step?
+
+Launch blocker examples:
+
+- A production database URL is stored in an MCP config.
+- A broad filesystem tool can write outside the app repository.
+- A shell or SQL tool is exposed to untrusted prompts without environment separation.
+
+Use `check-mcp` findings as the starting inventory, then manually inspect any tool that can read secrets or change state.
+
+## Supabase And Storage
+
+For Supabase apps, launch only after the data model has an ownership story.
+
+Check:
+
+- Sensitive tables have RLS enabled.
+- Policies use `auth.uid()` or tenant membership checks tied to the row.
+- Write policies use `WITH CHECK` so users cannot insert or move rows into another tenant.
+- Storage buckets and `storage.objects` policies are scoped by owner, tenant, or object path.
+- Service-role keys stay server-only and are not used in browser code.
+
+Manual verification should still use the two-account flow above. Scanner findings can point to weak policies, but the actual product workflow determines whether access is correctly isolated.
+
+## Secrets, Env, And Deploy
+
+Before launch:
+
+- Rotate any real secret that was committed, pasted into a public issue, or printed in a public log.
+- Confirm examples use inert placeholders, not real-looking provider tokens.
+- Confirm `NEXT_PUBLIC_*` variables contain only values that are safe for browsers.
+- Check `.env.example` or deploy docs include required production variables without revealing secret values.
+- Confirm Vercel, Netlify, or other deploy settings match runtime expectations: API routes are not accidentally static, and Node-only libraries are not deployed to incompatible Edge runtimes.
+
+## CI And PR Review
+
+Minimum repository workflow:
+
+- CI runs tests on pull requests and pushes to the default branch.
+- `ai-saas-guard pr-risk` runs with enough git history to compare against the base branch.
+- SARIF or markdown output is used when reviewers need scan results in GitHub.
+- Large AI-generated pull requests are split when they combine UI, auth, database, billing, and deploy changes.
+
+Review the first files named by `pr-risk` before reviewing cosmetic changes. If a base ref is missing, fix checkout depth or fetch history before trusting the PR risk result.
+
+## Rollback And Incident Readiness
+
+Before inviting real users, define:
+
+- How to disable paid access changes without deleting customer data.
+- How to revoke or rotate leaked keys.
+- How to roll back a failed deployment.
+- How to pause new signups or billing flows.
+- Where webhook delivery failures, auth errors, and database policy denials are logged.
+- Who decides whether a finding is a launch blocker or an accepted risk.
+
+The goal is not a perfect process. The goal is that the founder can answer what happens when auth, billing, deploy, or data isolation fails on launch day.
+
+## Founder Sign-Off
+
+A launch-ready review should leave behind short evidence, not just a feeling.
+
+Use this minimal sign-off:
+
+| Area | Evidence to keep |
+| --- | --- |
+| CLI preflight | Command output or CI link for `scan` and focused checks |
+| Two-account authorization | User A/User B notes with tested object types and rejected actions |
+| Stripe | Webhook replay notes for success, failure, update, cancellation, refund, duplicate, and out-of-order paths |
+| Supabase | RLS and storage policy review notes |
+| MCP | Reviewed MCP config files and disabled or constrained risky tools |
+| Secrets | Rotation notes or confirmation that only placeholders were found |
+| Deploy | Production env and runtime checks |
+| Rollback | Known rollback command or deploy platform rollback path |
+
+If any row is blank for a product surface the app actually uses, treat it as a must-verify item before launch.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.5.0`
+- Current version: `0.7.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.5.0`
+- GitHub Release: `v0.7.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
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.5.0`.
+1. Create and review a release tag such as `v0.7.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

@@ -39,6 +39,7 @@ Do not market it as a full pentest, full SAST platform, or proof that an app is
 Implemented surfaces:
 
 - secret-like values and risky public env exposure
+- founder-readable launch-readiness checklist for two-account authorization, Stripe webhook verification, MCP config review, Supabase, deploy, CI, and rollback checks
 - Stripe webhook signature, raw body, idempotency, and lifecycle handler heuristics
 - Stripe webhook replay cookbook for checkout, renewal failure, updates, cancellation, refunds, duplicate delivery, and out-of-order review
 - Supabase RLS, tenant membership, ownership filter, weak `WITH CHECK`, and storage object policy heuristics
@@ -48,7 +49,8 @@ Implemented surfaces:
 - PR diff risk triage for auth, billing, RLS, env, tests removed, and large mixed diffs
 - PR diff diagnostics when a base ref or shallow checkout prevents comparison
 - PR-focused markdown summary output for GitHub step summaries or PR comments
-- project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, and default fail thresholds
+- project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, path-specific suppressions, and default fail thresholds
+- rule stability labels in catalog metadata, public rule docs, and SARIF rule properties
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -100,7 +102,7 @@ GitHub Project:
 
 Current issue set:
 
-- #1 Add launch-readiness checklist content
+- No open roadmap issues after the `v0.7.0` suppression and stability release.
 
 CI:
 
@@ -112,7 +114,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.5.0`
+- Current release line: `v0.7.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.
@@ -139,9 +141,7 @@ Not allowed:
 
 Recommended order:
 
-1. Add launch-readiness checklist content.
-2. Improve false-positive suppression and rule stability labels.
-3. Add a GitHub App design note for the potential hosted layer.
+1. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -2,7 +2,37 @@
 
 `ai-saas-guard` rules are deterministic heuristics. They are designed to produce a focused verification queue, not a complete vulnerability list.
 
-Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so SARIF output, public docs, and future config work can share stable rule IDs. Current published rules use the `default` stability level.
+Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so SARIF output, public docs, and config work can share stable rule IDs, default severities, and stability labels.
+
+## Stability Labels
+
+Stability labels describe how much confidence reviewers should place in a finding before manual verification. They are not severity levels.
+
+| Stability | Meaning | Examples |
+| --- | --- | --- |
+| Strict | High-confidence evidence that should rarely be suppressed without a written reason. | Committed secret-like values, public Stripe secrets, unsigned Stripe webhooks, broad Supabase RLS policies. |
+| Default | Routine launch-readiness heuristic with useful evidence and an expected manual verification step. | Missing Stripe lifecycle events, weak Supabase ownership checks, MCP side-effect inventory. |
+| Experimental | Higher-noise heuristic meant to prioritize review, not prove a defect. | API ownership hints, rate-limit hints, missing env docs, PR risk triage. |
+
+SARIF output includes the rule stability in `properties["ai-saas-guard/stability"]` and a `stability:<level>` tag for code scanning consumers.
+
+## Suppressing False Positives
+
+Prefer fixing risky code over suppressing findings. When a finding is a reviewed false positive for a specific generated file, fixture, or documented launch exception, use path-specific `suppressions` in `.ai-saas-guard.json` instead of disabling the whole rule:
+
+```json
+{
+  "suppressions": [
+    {
+      "ruleId": "stripe.webhook.missing-idempotency",
+      "paths": ["app/api/stripe/webhook/route.ts"],
+      "reason": "Temporary exception; duplicate-event behavior is covered by integration tests."
+    }
+  ]
+}
+```
+
+`paths` are relative globs. Examples: `generated/**`, `tests/fixtures/**`, and `app/api/stripe/webhook/route.ts`.
 
 ## Secrets And Public Env
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",