ai-saas-guard 0.1.3 → 0.3.0

package/README.md

@@ -41,7 +41,7 @@ It is intentionally evidence-first. Findings include a rule ID, severity, file e
 
 This repository is public on GitHub.
 
-The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. If you need stricter supply-chain pinning in CI, pin the GitHub Action to a reviewed commit SHA instead of a mutable tag.
+The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag for controlled upgrades, or a reviewed commit SHA for stricter supply-chain pinning.
 
 | Area | Status |
 | --- | --- |
@@ -50,8 +50,9 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Local CLI from source | Available for development |
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
-| Versioned Action tags | `v0.1.3` |
-| npm package | `ai-saas-guard@0.1.3` |
+| Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
+| Versioned Action tags | `v0.3.0`, `v0` |
+| npm package | `ai-saas-guard@0.3.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -76,6 +77,8 @@ Machine-readable output:
 ```bash
 npx ai-saas-guard@latest scan --root /path/to/your-saas --json
 npx ai-saas-guard@latest scan --root /path/to/your-saas --sarif > ai-saas-guard.sarif
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --markdown > ai-saas-guard-pr.md
+npx ai-saas-guard@latest scan --root /path/to/your-saas --config <file> --json
 npx ai-saas-guard@latest scan --root /path/to/your-saas --fail-on high
 ```
 
@@ -148,9 +151,11 @@ 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
 
 ```bash
 node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
+node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --markdown
 ```
 
 If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` instead of silently reporting a clean or empty diff. In GitHub Actions, use `actions/checkout` with `fetch-depth: 0` when you need merge-base comparison against `origin/main`.
@@ -160,14 +165,33 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 | Command | Purpose |
 | --- | --- |
 | `scan` | Broad local launch preflight across secrets, Stripe, Supabase, MCP, API routes, and deploy config |
-| `pr-risk` | Classify the current git diff or a base branch diff for review priority |
+| `pr-risk` | Classify the current git diff or a base branch diff for review priority; supports JSON, SARIF, and PR-focused markdown |
 | `check-supabase` | Inspect migrations and policy files for RLS and ownership risks |
 | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
 | `check-mcp` | Inventory MCP configs and classify side effects |
 
+## Project Configuration
+
+Add `.ai-saas-guard.json` at the repository root to tune findings without changing scanner code. The CLI auto-loads this file from `--root` when it exists. Use `--config <file>` to point to a different JSON file.
+
+```json
+{
+  "failOn": "high",
+  "rules": {
+    "stripe.webhook.missing-signature": "off",
+    "stripe.webhook.missing-idempotency": "critical",
+    "deploy.env.example-missing": "info"
+  }
+}
+```
+
+`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.
+
+`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 the latest release tag 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.3.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -185,18 +209,19 @@ jobs:
       - uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
-      - uses: zr9959/ai-saas-guard@v0.1.3
+      - uses: zr9959/ai-saas-guard@v0
         with:
           command: pr-risk
           root: ${{ github.workspace }}
           base: origin/main
           fail-on: high
+          config: .ai-saas-guard.json
 ```
 
 For SARIF upload:
 
 ```yaml
-      - uses: zr9959/ai-saas-guard@v0.1.3
+      - uses: zr9959/ai-saas-guard@v0
         with:
           command: scan
           format: sarif
@@ -206,7 +231,22 @@ For SARIF upload:
           sarif_file: ai-saas-guard.sarif
 ```
 
-For maximum reproducibility, replace `v0.1.3` with the full commit SHA from the release notes.
+For PR-readable markdown in the Actions run:
+
+```yaml
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          format: markdown
+          output: ai-saas-guard-pr.md
+      - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
+```
+
+Use markdown for reviewer-facing PR triage and SARIF for GitHub code scanning alerts. See [docs/github-action.md](docs/github-action.md) for copy-paste workflows and trade-offs.
+
+For maximum reproducibility, replace `v0` with the full commit SHA from the release notes.
 
 ## Ignore File
 
@@ -274,17 +314,16 @@ Open-source core:
 - local CLI
 - deterministic scanner rules
 - vulnerable and safe fixtures
-- JSON and SARIF output
+- JSON, SARIF, and PR-focused markdown output
 - GitHub Action wrapper
 - rule documentation
 
 Near-term priorities:
 
-- PR comment summary mode
-- configurable severity and rule toggles
 - expanded Supabase RLS fixtures
 - Stripe webhook replay cookbook
-- SARIF upload workflow example
+- launch-readiness checklist content
+- false-positive suppression and rule stability labels
 
 Potential paid layer later:
 

package/action.yml

@@ -12,7 +12,7 @@ inputs:
     required: false
     default: ${{ github.workspace }}
   format:
-    description: "Output format: terminal, json, or sarif."
+    description: "Output format: terminal, json, sarif, or markdown."
     required: false
     default: terminal
   fail-on:
@@ -23,6 +23,10 @@ inputs:
     description: Base ref for pr-risk.
     required: false
     default: ""
+  config:
+    description: Optional ai-saas-guard JSON config path.
+    required: false
+    default: ""
   output:
     description: Optional path to write output while also keeping the command exit code.
     required: false
@@ -49,6 +53,7 @@ runs:
         INPUT_FORMAT: ${{ inputs.format }}
         INPUT_FAIL_ON: ${{ inputs.fail-on }}
         INPUT_BASE: ${{ inputs.base }}
+        INPUT_CONFIG: ${{ inputs.config }}
         INPUT_OUTPUT: ${{ inputs.output }}
       run: |
         set -o pipefail
@@ -62,7 +67,7 @@ runs:
         esac
 
         case "${INPUT_FORMAT}" in
-          terminal|json|sarif) ;;
+          terminal|json|sarif|markdown) ;;
           *)
             echo "Invalid format input: ${INPUT_FORMAT}" >&2
             exit 2
@@ -83,6 +88,8 @@ runs:
           args+=("--json")
         elif [ "${INPUT_FORMAT}" = "sarif" ]; then
           args+=("--sarif")
+        elif [ "${INPUT_FORMAT}" = "markdown" ]; then
+          args+=("--markdown")
         fi
 
         if [ "${INPUT_FAIL_ON}" != "none" ]; then
@@ -93,6 +100,10 @@ runs:
           args+=("--base" "${INPUT_BASE}")
         fi
 
+        if [ -n "${INPUT_CONFIG}" ]; then
+          args+=("--config" "${INPUT_CONFIG}")
+        fi
+
         if [ -n "${INPUT_OUTPUT}" ]; then
           node "${GITHUB_ACTION_PATH}/dist/cli.js" "${args[@]}" | tee -- "${INPUT_OUTPUT}"
         else

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
+import { applyGuardConfig, loadGuardConfig } from "./config.js";
 import { checkMcp, checkStripe, checkSupabase, classifyPrRisk, scanRepository } from "./index.js";
 import { formatJsonReport } from "./report/json.js";
+import { formatMarkdownReport } from "./report/markdown.js";
 import { formatSarifReport } from "./report/sarif.js";
 import { formatTerminalReport } from "./report/terminal.js";
 async function main(argv) {
@@ -10,6 +12,7 @@ async function main(argv) {
         process.stdout.write(helpText());
         return 0;
     }
+    const config = await loadGuardConfig(args.rootDir, args.configPath);
     let report;
     switch (args.command) {
         case "scan":
@@ -31,9 +34,11 @@ async function main(argv) {
             process.stderr.write(`Unknown command: ${String(args.command)}\n\n${helpText()}`);
             return 2;
     }
+    report = applyGuardConfig(report, config);
     process.stdout.write(formatReport(report, args.format));
-    if (shouldFail(report, args.failOn)) {
-        process.stderr.write(`Failing because findings met --fail-on ${args.failOn}\n`);
+    const failOn = args.failOn ?? config.failOn;
+    if (shouldFail(report, failOn)) {
+        process.stderr.write(`Failing because findings met --fail-on ${failOn}\n`);
         return 1;
     }
     return 0;
@@ -57,10 +62,14 @@ function parseArgs(argv) {
             result.format = "sarif";
             continue;
         }
+        if (arg === "--markdown") {
+            result.format = "markdown";
+            continue;
+        }
         if (arg === "--format") {
             const value = argv[index + 1];
-            if (value !== "terminal" && value !== "json" && value !== "sarif") {
-                throw new Error("--format requires terminal, json, or sarif");
+            if (value !== "terminal" && value !== "json" && value !== "sarif" && value !== "markdown") {
+                throw new Error("--format requires terminal, json, sarif, or markdown");
             }
             result.format = value;
             index += 1;
@@ -82,6 +91,14 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (arg === "--config") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--config requires a path");
+            result.configPath = resolve(value);
+            index += 1;
+            continue;
+        }
         if (arg === "--base") {
             const value = argv[index + 1];
             if (!value)
@@ -108,6 +125,8 @@ function formatReport(report, format) {
         return formatJsonReport(report);
     if (format === "sarif")
         return formatSarifReport(report);
+    if (format === "markdown")
+        return formatMarkdownReport(report);
     return `${formatTerminalReport(report)}\n`;
 }
 function shouldFail(report, failOn) {
@@ -134,11 +153,11 @@ function helpText() {
 Repo-local launch-readiness scanner for AI-built SaaS apps.
 
 Usage:
-  ai-saas-guard scan [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  ai-saas-guard check-supabase [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  ai-saas-guard check-stripe [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  ai-saas-guard check-mcp [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  ai-saas-guard pr-risk [--root <repo>] [--base <branch>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard scan [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-supabase [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-stripe [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-mcp [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard pr-risk [--root <repo>] [--config <file>] [--base <branch>] [--json|--sarif|--markdown] [--fail-on <severity>]
 
 Defaults:
   - read-only
@@ -146,6 +165,8 @@ Defaults:
   - no account or login required
   - terminal output by default, JSON with --json
   - SARIF output for GitHub code scanning with --sarif
+  - PR-focused markdown summary with --markdown
+  - project config auto-loaded from .ai-saas-guard.json when present
 `;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { BaseReport, Severity } from "./types.js";
+export declare const defaultConfigFileName = ".ai-saas-guard.json";
+export type RuleConfigValue = "off" | Severity;
+export interface GuardConfig {
+    sourcePath?: string;
+    failOn?: Severity | "none";
+    rules: Record<string, RuleConfigValue>;
+}
+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

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { summarizeFindings, sortFindings } from "./report/findings.js";
+import { getRuleMetadata } from "./rules/catalog.js";
+export const defaultConfigFileName = ".ai-saas-guard.json";
+export async function loadGuardConfig(rootDir, explicitPath) {
+    const sourcePath = explicitPath ? resolve(explicitPath) : resolve(rootDir, defaultConfigFileName);
+    let content;
+    try {
+        content = await readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        if (!explicitPath && isNotFoundError(error))
+            return { rules: {} };
+        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)
+        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 }];
+    }));
+    return {
+        ...report,
+        findings,
+        summary: summarizeFindings(findings)
+    };
+}
+function parseGuardConfig(content, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in config file ${sourcePath}: ${errorMessage(error)}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Invalid config file ${sourcePath}: expected a JSON object`);
+    }
+    const failOn = parsed.failOn;
+    if (failOn !== undefined && !isFailOnValue(failOn)) {
+        throw new Error("Invalid config failOn: expected critical, high, medium, low, info, or none");
+    }
+    const rawRules = parsed.rules ?? {};
+    if (!isPlainObject(rawRules)) {
+        throw new Error("Invalid config rules: expected an object keyed by rule ID");
+    }
+    const rules = {};
+    for (const [ruleId, value] of Object.entries(rawRules)) {
+        if (!getRuleMetadata(ruleId)) {
+            throw new Error(`Unknown rule ID in config: ${ruleId}`);
+        }
+        if (!isRuleConfigValue(value)) {
+            throw new Error(`Invalid config for rule ${ruleId}: expected off, critical, high, medium, low, or info`);
+        }
+        rules[ruleId] = value;
+    }
+    return {
+        sourcePath,
+        failOn,
+        rules
+    };
+}
+function isRuleConfigValue(value) {
+    return value === "off" || isSeverity(value);
+}
+function isFailOnValue(value) {
+    return value === "none" || isSeverity(value);
+}
+function isSeverity(value) {
+    return value === "critical" || value === "high" || value === "medium" || value === "low" || value === "info";
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNotFoundError(error) {
+    return isPlainObject(error) && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -3,8 +3,10 @@ export { checkStripe } from "./commands/checkStripe.js";
 export { checkSupabase } from "./commands/checkSupabase.js";
 export { checkMcp } from "./commands/checkMcp.js";
 export { classifyPrRisk } from "./commands/prRisk.js";
+export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./config.js";
 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 { RuleMetadata, RuleStability } from "./rules/catalog.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { checkStripe } from "./commands/checkStripe.js";
 export { checkSupabase } from "./commands/checkSupabase.js";
 export { checkMcp } from "./commands/checkMcp.js";
 export { classifyPrRisk } from "./commands/prRisk.js";
+export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./config.js";
 export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";

package/dist/report/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { BaseReport } from "../types.js";
+export declare function formatMarkdownReport(report: BaseReport): string;

package/dist/report/markdown.js

@@ -0,0 +1,83 @@
+export function formatMarkdownReport(report) {
+    if (report.command === "pr-risk")
+        return `${formatPrRiskMarkdown(report)}\n`;
+    return `${formatGenericMarkdown(report)}\n`;
+}
+function formatPrRiskMarkdown(report) {
+    const lines = [];
+    lines.push("## ai-saas-guard PR risk summary");
+    lines.push("");
+    lines.push(summaryLine(report));
+    if (report.categories.length > 0) {
+        lines.push("");
+        lines.push(`**Risk categories:** ${report.categories.map((category) => `\`${category}\``).join(", ")}`);
+    }
+    lines.push("");
+    lines.push("### Review first");
+    if (report.topRiskyFiles.length === 0) {
+        lines.push("");
+        lines.push("No changed trust-boundary files were classified by `pr-risk`.");
+    }
+    else {
+        lines.push("");
+        lines.push("| File | Score | Categories | Diff |");
+        lines.push("| --- | ---: | --- | ---: |");
+        for (const file of report.topRiskyFiles.slice(0, 10)) {
+            lines.push(`| \`${escapeMarkdownTableCell(file.path)}\` | ${file.score} | ${file.categories.map((category) => `\`${escapeMarkdownTableCell(category)}\``).join("<br>")} | +${file.added} / -${file.removed} |`);
+        }
+    }
+    lines.push("");
+    lines.push("### Required verification");
+    appendList(lines, report.requiredTests.length > 0 ? report.requiredTests : report.reviewChecklist);
+    lines.push("");
+    lines.push("### Suggested PR split");
+    appendList(lines, report.suggestedSplit.length > 0 ? report.suggestedSplit : ["No split suggestion from the current diff."]);
+    lines.push("");
+    lines.push("### Findings");
+    appendFindings(lines, report.findings);
+    return lines.join("\n");
+}
+function formatGenericMarkdown(report) {
+    const lines = [];
+    lines.push(`## ai-saas-guard ${report.command}`);
+    lines.push("");
+    lines.push(summaryLine(report));
+    lines.push("");
+    lines.push("### Findings");
+    appendFindings(lines, report.findings);
+    return lines.join("\n");
+}
+function summaryLine(report) {
+    return `**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}`;
+}
+function appendList(lines, items) {
+    for (const item of items) {
+        lines.push(`- ${item}`);
+    }
+}
+function appendFindings(lines, findings) {
+    if (findings.length === 0) {
+        lines.push("");
+        lines.push("No heuristic launch-readiness risks found by this command.");
+        return;
+    }
+    for (const [index, finding] of findings.entries()) {
+        lines.push("");
+        lines.push(`${index + 1}. **[${finding.severity.toUpperCase()}] ${finding.title}**`);
+        lines.push(`   - Rule: \`${finding.ruleId}\``);
+        lines.push(`   - Evidence: ${formatEvidence(finding.evidence[0])}`);
+        lines.push(`   - Why: ${finding.why}`);
+        lines.push(`   - Verify: ${finding.suggestedVerification}`);
+        lines.push(`   - Fix direction: ${finding.suggestedFix}`);
+    }
+}
+function formatEvidence(evidence) {
+    if (!evidence)
+        return "`none`";
+    const location = evidence.line ? `${evidence.file}:${evidence.line}` : evidence.file;
+    const detail = evidence.snippet ?? evidence.match;
+    return detail ? `\`${location}\` - ${detail}` : `\`${location}\``;
+}
+function escapeMarkdownTableCell(value) {
+    return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}

package/docs/github-action.md

@@ -0,0 +1,85 @@
+# GitHub Action Usage
+
+`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.3.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+
+## PR Summary
+
+Use markdown when reviewers need a short, evidence-first summary of risky files, required verification, and suggested PR split.
+
+```yaml
+name: ai-saas-guard-pr-summary
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pr-summary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          config: .ai-saas-guard.json
+          format: markdown
+          output: ai-saas-guard-pr.md
+      - 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.
+
+## Project Config
+
+The Action auto-loads `.ai-saas-guard.json` from `root` when the file exists. Use the `config` input when the policy file lives somewhere else or when you want the workflow to be explicit:
+
+```yaml
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: scan
+          root: ${{ github.workspace }}
+          config: .ai-saas-guard.json
+          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.
+
+## SARIF Upload
+
+Use SARIF when you want findings to appear in GitHub code scanning alerts.
+
+```yaml
+name: ai-saas-guard-sarif
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  code-scanning:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: scan
+          root: ${{ github.workspace }}
+          format: sarif
+          output: ai-saas-guard.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          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.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.1.3`
+- Current version: `0.3.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.1.3`
+- GitHub Release: `v0.3.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.1.3`.
+1. Create and review a release tag such as `v0.3.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

@@ -46,6 +46,8 @@ Implemented surfaces:
 - Next/Vercel deploy and runtime footguns
 - 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
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -98,13 +100,8 @@ GitHub Project:
 Current issue set:
 
 - #1 Add launch-readiness checklist content
-- #2 Add GitHub Action release packaging
-- #3 Add configurable rule severity and rule toggles
-- #4 Add PR comment summary mode
 - #5 Write Stripe webhook replay cookbook
-- #6 Add SARIF upload workflow example
 - #7 Expand Supabase RLS fixtures and ownership patterns
-- #8 Publish ai-saas-guard to npm
 
 CI:
 
@@ -116,7 +113,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.1.3`
+- Current release line: `v0.3.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.
@@ -143,13 +140,11 @@ Not allowed:
 
 Recommended order:
 
-1. Add PR comment summary mode.
-2. Add configurable severity and rule toggles.
-3. Expand Supabase RLS fixtures and ownership patterns.
-4. Write Stripe webhook replay cookbook.
-5. Add SARIF upload workflow example.
-6. Improve false-positive suppression and rule stability labels.
-7. Add a GitHub App design note for the potential hosted layer.
+1. Expand Supabase RLS fixtures and ownership patterns.
+2. Write Stripe webhook replay cookbook.
+3. Add launch-readiness checklist content.
+4. Improve false-positive suppression and rule stability labels.
+5. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/package.json

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