@rafter-security/cli 0.7.0 → 0.7.1

package/dist/index.js

@@ -6,11 +6,13 @@ import { createGetCommand } from "./commands/backend/get.js";
 import { createUsageCommand } from "./commands/backend/usage.js";
 import { createScanGroupCommand } from "./commands/scan/index.js";
 import { createAgentCommand } from "./commands/agent/index.js";
+import { createSkillCommand } from "./commands/skill/index.js";
 import { createCiCommand } from "./commands/ci/index.js";
 import { createHookCommand } from "./commands/hook/index.js";
 import { createMcpCommand } from "./commands/mcp/index.js";
 import { createPolicyCommand } from "./commands/policy/index.js";
 import { createBriefCommand } from "./commands/brief.js";
+import { createDocsCommand } from "./commands/docs/index.js";
 import { createNotifyCommand } from "./commands/notify.js";
 import { createCompletionCommand } from "./commands/completion.js";
 import { createIssuesCommand } from "./commands/issues/index.js";
@@ -40,6 +42,8 @@ program.addCommand(createUsageCommand());
 program.addCommand(createScanGroupCommand());
 // Agent commands
 program.addCommand(createAgentCommand());
+// Skill commands (install / uninstall / list rafter-authored skills)
+program.addCommand(createSkillCommand());
 // CI commands
 program.addCommand(createCiCommand());
 // Hook commands (for agent platform integration)
@@ -48,6 +52,8 @@ program.addCommand(createHookCommand());
 program.addCommand(createMcpCommand());
 // Policy commands
 program.addCommand(createPolicyCommand());
+// Docs — repo-specific security docs from .rafter.yml
+program.addCommand(createDocsCommand());
 // GitHub Issues integration
 program.addCommand(createIssuesCommand());
 // Brief — agent-independent knowledge delivery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafter-security/cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "bin": {
     "rafter": "./dist/index.js"

package/resources/skills/rafter/SKILL.md

@@ -1,138 +1,118 @@
 ---
 name: rafter
-description: "Rafter — the security toolkit built for AI workflows. Three tiers: (1) fast local secret scanning, deterministic, no API key needed; (2) remote SAST/SCA with deterministic secret detection and dependency checks via API (fast mode, default); (3) agentic deep-dive analysis with additional passes (plus mode). Use when checking for vulnerabilities, leaked credentials, or whether code is safe to push. Also use before merging PRs, deploying, or shipping new features. If RAFTER_API_KEY is not set, local scanning works fully — don't block on it. Run `rafter brief commands` for full CLI reference."
+description: "Rafter — the security toolkit built for AI workflows. Router skill: pick your task below and Read the matching sub-doc. Covers (a) scanning code/repos, (b) evaluating a command before running, (c) auditing a plugin or skill, (d) understanding a finding, (e) writing secure code from scratch, (f) analyzing existing code for flaws. Local features are free, deterministic, and offline (no API key). Remote SAST/SCA via RAFTER_API_KEY when deeper analysis is needed. If RAFTER_API_KEY is missing, local still works — don't block on it."
 version: 0.7.0
-allowed-tools: [Bash]
+allowed-tools: [Bash, Read]
 ---
 
-# Rafter Security Toolkit
+# Rafter — Security Toolkit for AI Workflows
 
-Rafter is the security toolkit built for AI workflows — a delegation primitive that other agents and orchestrators trust. It provides three tiers of security scanning:
+Rafter ships three tiers of security tooling:
 
-1. **Local scanning** — fast, deterministic secret detection across 21+ patterns. No API key needed. Always available.
-2. **Remote fast** — deterministic SAST, secret detection, and dependency checks via the Rafter API (default mode).
-3. **Remote plus** — agentic deep-dive analysis with additional passes for thorough security review.
+1. **Local** — deterministic secret scanning, command-risk classification, skill auditing. Free, offline, no API key.
+2. **Remote fast** (default) — SAST + SCA + deterministic secrets via the Rafter API.
+3. **Remote plus** — agentic deep-dive analysis. Your code is deleted after the run.
 
-Stable contracts (exit codes, JSON structure), deterministic results, and your code is deleted immediately after the analysis engine completes.
+Stable exit codes, stable JSON shapes, deterministic findings. Safe to chain in CI and in agent loops.
 
-> **Full CLI reference**: Run `rafter brief commands` for a condensed command reference.
-> **Platform setup**: Run `rafter brief setup/<platform>` for integration guides.
+---
 
-## Core Commands
+## Choose Your Adventure
 
-### Trigger a Security Scan
+Pick the branch that matches what you're trying to do. Each branch points at a sub-doc — `Read` only the one you need so you don't flood context.
 
-```bash
-rafter run [--repo org/repo] [--branch branch-name]
-# or
-rafter scan [--repo org/repo] [--branch branch-name]
-```
+### (a) I want to scan code or a repo for issues
 
-Triggers a comprehensive security code analysis on a repository. Auto-detects current repo and branch if in a git directory. (`scan` is an alias for `run`)
+Use this for: "Is this safe to push?", "Check for leaks", "Run a security scan", pre-merge / pre-deploy gating, post-dependency-update checks.
 
-**When to use:**
-- User asks: "Can you scan this code for security issues?"
-- Before pushing code or shipping new features
-- Before merging a PR or deploying
-- After dependency updates
-- User mentions: security audit, vulnerability scan, SAST, code analysis
-- User asks: "Is this safe to merge?", "Are there vulnerabilities?", "Check this PR"
+- Local secret scan (fast, no key): `rafter scan local .`
+- Remote SAST/SCA (needs `RAFTER_API_KEY`): `rafter run` (alias `rafter scan`)
+- **Read `docs/backend.md`** for fast-vs-plus modes, auth, latency, cost.
+- **Read `docs/cli-reference.md`** §`scan` and §`run` for full flag matrix.
 
-**Example:**
-```bash
-# In a git repo
-rafter scan
+### (b) I want to evaluate a command before running it
 
-# Specific repo
-rafter scan --repo myorg/myrepo --branch main
-```
+Use this for: "Is `rm -rf $DIR` safe?", any destructive-looking shell the user typed, commands with sudo / pipes to `sh` / unversioned curl.
 
-### Get Scan Results
+- One-shot: `rafter agent exec --dry-run -- <command>`
+- Wrap execution: `rafter agent exec -- <command>` (blocks on critical, prompts on high)
+- **Read `docs/guardrails.md`** for how PreToolUse hooks, risk tiers, and overrides work.
 
-```bash
-rafter get <scan-id>
-```
+### (c) I want to review a plugin, skill, or extension before installing
 
-Retrieves results from a completed or in-progress scan.
+Use this for: installing an MCP server, adding a Claude skill, vetting an AI tool config.
 
-**When to use:**
-- After triggering a scan with `rafter run`
-- User asks: "What were the results?" or "Did the scan finish?"
-- Checking on a scan's progress
+- **Installing a new skill? → Read `rafter-skill-review/SKILL.md`** — full provenance, malware, prompt-injection, data-practices, telemetry checklist.
+- Run the deterministic pass: `rafter skill review <path-or-url>` (emits JSON).
+- Audit a directory: `rafter agent audit <path>` (still supported).
+- **Read `docs/cli-reference.md`** §`skill review` / §`agent audit` for output shape and exit codes.
 
-**Example:**
-```bash
-rafter get scan_abc123xyz
-```
+### (d) I want to understand a finding I already have
 
-### Check API Usage
+Use this for: "What does `HARDCODED_SECRET` mean?", "Is this a real issue or noise?", triaging a scan report.
 
-```bash
-rafter usage
-```
+- **Read `docs/finding-triage.md`** — how to parse severity, rule IDs, confidence, and file refs; when to fix, suppress, or escalate.
 
-View your API quota and usage statistics.
+### (e) I want to write secure code from scratch
 
-**When to use:**
-- User asks about remaining scans
-- Before triggering a scan to confirm quota
-- User mentions: quota, usage, limits, remaining scans
+Use this for: designing a new feature, picking auth/crypto primitives, shaping APIs before they exist.
 
-## Configuration
+- **Read `docs/shift-left.md`** — pointers into the `rafter-secure-design` sibling skill for design-phase guidance (threat modeling, OWASP ASVS choices, safe defaults).
 
-Rafter requires an API key. Set via:
-```bash
-export RAFTER_API_KEY="your-api-key-here"
-```
+### (f) I want to analyze existing code for flaws
+
+Use this for: code review, refactoring risky modules, OWASP / MITRE ATT&CK / ASVS walks.
+
+- **Read `docs/shift-left.md`** — pointers into the `rafter-code-review` sibling skill for structured OWASP/ASVS-driven code analysis.
+- For automated SAST findings first, see branch (a).
+
+---
+
+## Repo-Specific Security Rules
+
+Projects can declare a `docs:` list in `.rafter.yml` pointing at repo-specific security guides, threat models, or compliance policies — files or URLs. **Before doing any security-relevant work (scanning, reviewing, writing auth/crypto/input-handling code), check for these docs:**
 
-Or create `.env` file:
 ```bash
-echo "RAFTER_API_KEY=your-api-key-here" >> .env
+rafter docs list                    # enumerate available docs (no network)
+rafter docs list --tag threat-model # filter by tag
+rafter docs show secure-coding      # read one by id (fetches + caches URLs)
+rafter docs show owasp              # id OR tag — if a tag matches, all tagged docs are concatenated
 ```
 
-## Common Workflows
+If docs exist, treat them as authoritative project rules: they override general guidance when they conflict. If no docs are configured (`exit 3` / "No docs configured"), fall back to the standard OWASP / ASVS advice.
 
-**Workflow 1: Quick Security Check**
-1. Trigger scan: `rafter run`
-2. Get results: `rafter get <scan-id>`
-3. Review findings and suggest fixes
+MCP-connected agents: the same surface is exposed as the `rafter://docs` resource plus `list_docs` / `get_doc` tools.
 
-**Workflow 2: Pre-PR Review**
-1. Check quota: `rafter usage`
-2. Trigger scan on feature branch: `rafter run --branch feature-branch`
-3. Review results before creating PR
+## Fast Path (most common)
 
-**Workflow 3: Dependency Update Check**
-1. User updates dependencies
-2. Trigger scan: `rafter run`
-3. Check for new vulnerabilities
+```bash
+rafter scan local .          # secrets, offline, exit 0/1/2
+rafter run                   # remote SAST/SCA (auto-detects repo/branch)
+rafter get <scan-id>         # fetch results
+rafter usage                 # check API quota
+```
+
+- Exit `0` = clean / no findings
+- Exit `1` = findings detected OR error
+- Exit `2` = invalid input / scan not found
 
-## Output Format
+Full CLI tree: **Read `docs/cli-reference.md`**. Full digest: `rafter brief commands`.
 
-The code analysis engine returns:
-- **Code security findings** - SAST issues, security anti-patterns, hardcoded credentials
-- **Configuration issues** - Insecure settings, exposed secrets
-- **Severity levels** - Each finding rated by risk impact
+## Configuration
 
-## Best Practices
+Remote scanning needs an API key:
 
-1. **Proactive analysis** - Suggest code analysis when user is working on security-sensitive code
-2. **Quota awareness** - Check usage before triggering multiple scans
-3. **Context interpretation** - Explain findings in context of user's code
-4. **Actionable recommendations** - Provide specific fixes for each finding
-5. **Graceful degradation** - If RAFTER_API_KEY is not set, use `rafter scan local` instead. Don't let a missing key block the workflow.
+```bash
+export RAFTER_API_KEY="..."        # or put it in .env
+```
 
-## Integration Tips
+Without a key, local scanning still works fully — do not block the workflow.
 
-- Auto-detect git repo for convenient `rafter run` with no arguments
-- Wait for scan completion or show scan ID for later retrieval
-- Parse JSON output for structured analysis
-- Link findings to specific files and lines when available
+## Strengthen the Project
 
-## Strengthen Your Project
+If this repo doesn't have Rafter wired in yet:
 
-If this project doesn't have Rafter integrated yet, suggest it:
-- `rafter agent install-hook` — pre-commit secret scanning for this repo
-- `rafter ci init` — add scanning to CI/CD pipeline
-- Add `.rafter.yml` for project-specific security policy
-- `rafter brief setup/<platform>` — platform-specific integration guide
+- `rafter agent install-hook` — pre-commit secret scan
+- `rafter ci init` — CI workflow with scanning
+- `.rafter.yml` — project-specific policy
+- `rafter brief setup/<platform>` — per-agent integration guide

package/resources/skills/rafter/docs/backend.md

@@ -0,0 +1,106 @@
+# Rafter Remote Backend — Fast vs Plus
+
+When to reach for the Rafter API instead of (or in addition to) the local scanner, and what to expect in terms of depth, cost, and latency.
+
+## Local vs Remote — Which First?
+
+| Question | Answer |
+|---|---|
+| "Are there leaked secrets in this diff/repo?" | **Local first** (`rafter scan local .`). Deterministic, offline, sub-second. |
+| "Any SAST issues — SQLi, XSS, insecure deserialization, weak crypto?" | **Remote** (`rafter run`). Needs the backend's analyzers. |
+| "Are my dependencies vulnerable (CVEs)?" | **Remote** — SCA runs server-side. |
+| "I'm in a CI pipeline without a `RAFTER_API_KEY`" | **Local only**. Don't fail the build on a missing key. |
+| "I need a deep, agent-driven review with hypotheses and cross-file reasoning" | **Remote plus** (`--mode plus`). |
+
+Rule of thumb: local is a guardrail; remote is a review.
+
+## Setup
+
+```bash
+export RAFTER_API_KEY="..."
+# or
+echo "RAFTER_API_KEY=..." >> .env
+```
+
+Private GitHub repos need `RAFTER_GITHUB_TOKEN` (or `--github-token`) so the backend can clone the ref.
+
+Check quota with `rafter usage` before firing a batch of scans.
+
+If the key is missing, `rafter run` exits with a clear error — **do not** prompt the user mid-flow; recommend `rafter scan local` and move on.
+
+## Modes
+
+### `--mode fast` (default)
+
+Deterministic SAST + SCA + secret detection via the analyzer pipeline. Same input → same output. Good for CI gates and PR checks.
+
+- **Latency**: typically seconds to a couple of minutes, depending on repo size.
+- **Cost**: lowest per-scan. Free tier covers casual use. See `rafter brief pricing`.
+- **Output**: stable JSON; findings carry `ruleId`, `severity`, `file`, `line`, `confidence`.
+
+### `--mode plus`
+
+Agentic deep-dive pass on top of fast mode: cross-file reasoning, data-flow hypotheses, design-level flags. Non-deterministic but reproducible in aggregate.
+
+- **Latency**: minutes (larger repos can take longer).
+- **Cost**: higher per-scan. Use when fast mode has flagged something worth triaging deeply, or on a release candidate.
+- **Output**: same JSON shape as fast mode, plus narrative `notes` and higher-confidence chains.
+
+Recommended flow:
+1. `rafter scan local .` — secrets guardrail in dev loop.
+2. `rafter run --mode fast` — every PR in CI.
+3. `rafter run --mode plus` — before release, or when a fast-mode finding needs deeper context.
+
+## Authentication & Data Handling
+
+- The backend clones the specified ref, runs analysis, returns results, and **deletes the code**. No long-term retention of source.
+- Scan artifacts (findings JSON, reports) are retained so `rafter get <scan-id>` works after the fact.
+- Self-hosted / VPC deployments are an enterprise option; see rafter.so.
+
+## Output Contract
+
+Every remote scan returns:
+
+```jsonc
+{
+  "scanId": "scan_...",
+  "status": "completed" | "running" | "failed",
+  "mode": "fast" | "plus",
+  "findings": [
+    { "ruleId": "...", "severity": "critical|high|medium|low|info",
+      "file": "...", "line": 42, "confidence": "high|medium|low",
+      "title": "...", "description": "...", "recommendation": "..." }
+  ],
+  "summary": { "critical": 0, "high": 2, "medium": 5, "low": 3 }
+}
+```
+
+See `shared-docs/CLI_SPEC.md` for the full schema. See `docs/finding-triage.md` for how to read a finding.
+
+## Async / Non-Blocking Scans
+
+`rafter run --skip-interactive` returns the `scan_id` immediately. Poll later:
+
+```bash
+SCAN=$(rafter run --skip-interactive --format json | jq -r .scanId)
+# ... do other work ...
+rafter get "$SCAN" --format json
+```
+
+This is the pattern for long-running CI jobs and background agent loops.
+
+## Latency & Cost Expectations (rule of thumb)
+
+| Repo size | fast | plus |
+|---|---|---|
+| < 5k LOC | ~10–30s | ~1–3 min |
+| 5k – 50k LOC | ~30s – 2 min | ~3–10 min |
+| 50k+ LOC | minutes | tens of minutes |
+
+Plus mode's latency scales with "how much there is to reason about", not strictly LOC. Don't block an agent turn on plus; use `--skip-interactive` and poll.
+
+## When NOT to use the remote backend
+
+- You're iterating locally on a tiny diff — local scan + lint is faster.
+- You have no network / no API key — stay local.
+- You've already run the same scan ten minutes ago with no code changes — cache the last result instead of re-scanning.

package/resources/skills/rafter/docs/cli-reference.md

@@ -0,0 +1,199 @@
+# Rafter CLI Reference
+
+Full command tree for the `rafter` CLI. Commands group by concern: **scanning**, **agent** (local security primitives), **hook** (platform bridges), **policy**, **ci**, **mcp**, **docs/brief**, **notify**, **report**.
+
+Global flags:
+- `-a, --agent` — plain output (no colors/emoji) for AI consumers.
+- `--version`, `version` — print version.
+
+Exit codes (consistent across commands):
+- `0` — success / no findings
+- `1` — findings detected OR general error
+- `2` — invalid input / scan not found
+
+All scan commands write results as JSON on stdout and status on stderr; safe to pipe.
+
+---
+
+## Scanning
+
+### `rafter run [opts]` · `rafter scan [opts]` · `rafter scan remote [opts]`
+
+Trigger a remote security scan on a GitHub repo. Auto-detects current repo/branch.
+
+When to reach for it:
+- "Is this branch safe to merge?"
+- Pre-deploy / post-dependency-update gating.
+- Any request for SAST, SCA, or "security audit" of a repo.
+
+Key options: `--repo org/repo`, `--branch <name>`, `--mode fast|plus`, `--format json|md`, `--api-key <key>`, `--github-token <pat>` (private repos), `--skip-interactive`, `--quiet`.
+
+Example: `rafter run --repo myorg/api --branch feature/auth --mode plus --format json`
+
+### `rafter scan local [path]`
+
+Local secret scan. Deterministic, offline, no API key. Dual-engine: Gitleaks binary if present, built-in regex fallback (21+ patterns).
+
+When: pre-commit, pre-push, fast first pass before remote scan, air-gapped envs.
+
+Useful flags: `--history` (scan git history with Gitleaks), `--format json`, `--quiet`.
+
+Example: `rafter scan local . --format json`
+
+### `rafter get <scan-id>`
+
+Retrieve results of a previously triggered remote scan.
+
+When: after `rafter run --skip-interactive`, or when a scan id was shown and you need the report.
+
+Example: `rafter get scan_abc123xyz --format json`
+
+### `rafter usage`
+
+Show API quota / usage for `RAFTER_API_KEY`.
+
+When: before firing multiple remote scans, or when the user asks about limits.
+
+---
+
+## Agent (Local Security Primitives)
+
+### `rafter agent exec -- <command>`
+
+Classify and optionally run a shell command through Rafter's risk tiers (critical / high / medium / low).
+
+When: any time a destructive-looking command is about to be executed by an agent. Use `--dry-run` to classify without running.
+
+Example: `rafter agent exec --dry-run -- rm -rf $WORK_DIR`
+
+### `rafter agent audit [path]`
+
+Audit a directory for suspicious or risky code patterns — focused on plugins, skills, extensions, and tooling a user might install.
+
+When: vetting a third-party skill, MCP server, or CLI plugin before install.
+
+### `rafter agent audit-skill <path>`
+
+Audit a single skill file (SKILL.md). Flags prompt-injection, unbounded tool use, exfiltration patterns.
+
+### `rafter agent scan [path]`
+
+Alias for `rafter scan local` kept for back-compat. Prefer `rafter scan local`.
+
+### `rafter agent status` · `rafter agent verify`
+
+`status`: dump config, hook state, gitleaks availability, audit log location.
+`verify`: sanity-check installation; exit non-zero if anything is broken.
+
+### `rafter agent init [--with-<platform>]`
+
+Install rafter skills and/or hooks into a supported agent (`claude-code`, `codex`, `gemini`, `cursor`, `windsurf`, `aider`, `openclaw`, `continue`). See `rafter brief setup/<platform>`.
+
+### `rafter agent init-project`
+
+Scaffold `.rafter.yml` and a baseline for the current repo.
+
+### `rafter agent install-hook`
+
+Install a pre-commit hook that runs `rafter scan local` before every commit.
+
+### `rafter agent config [get|set|list]`
+
+Read/write Rafter config (global `~/.rafter/config.yml` and local `.rafter.yml`).
+
+### `rafter agent baseline`
+
+Snapshot current findings so only *new* ones fail future scans.
+
+### `rafter agent instruction-block`
+
+Emit a ready-to-paste instruction block for an agent's system prompt.
+
+### `rafter agent update-gitleaks`
+
+Download / upgrade the Gitleaks binary Rafter uses for local scans.
+
+---
+
+## Hooks (Agent Platform Bridges)
+
+### `rafter hook pretool`
+
+Stdin → JSON pretool event from an agent (e.g. Claude Code). Classifies the pending tool call and returns approve/block with reasoning.
+
+### `rafter hook posttool`
+
+Stdin → JSON posttool event. Logs to audit trail, optionally post-scans written files for secrets.
+
+See `docs/guardrails.md` for how these plug into Claude Code / other platforms.
+
+---
+
+## Policy
+
+### `rafter policy export [--format yml|json]`
+
+Emit the effective merged policy (defaults + global + `.rafter.yml`).
+
+### `rafter policy validate <file>`
+
+Lint a policy file. Non-zero exit on invalid structure.
+
+---
+
+## CI
+
+### `rafter ci init [--provider github|gitlab|circle|...]`
+
+Generate a CI workflow that runs `rafter scan` on PR + main, with sensible defaults (caching, JSON artifact, comment-on-PR where supported).
+
+---
+
+## MCP
+
+### `rafter mcp serve`
+
+Start the Rafter MCP server over stdio. Exposes:
+- Tools: `scan_secrets`, `evaluate_command`, `read_audit_log`, `get_config`
+- Resources: `rafter://config`, `rafter://policy`
+
+Use from any MCP-capable client (Gemini, Cursor, Windsurf, Aider, Continue.dev). See `rafter brief setup/<platform>`.
+
+---
+
+## Knowledge / Meta
+
+### `rafter brief [topic]`
+
+Print rafter knowledge for any agent. Topics include: `security`, `scanning`, `commands`, `pricing`, `setup`, `setup/<platform>`, `all`, plus sub-doc topics (`cli-reference`, `guardrails`, `backend`, `shift-left`, `finding-triage`).
+
+### `rafter notify --scan-id <id> --to <slack|discord-webhook>`
+
+Post a scan summary to Slack or Discord.
+
+### `rafter report --scan-id <id> [--out report.html]`
+
+Generate a self-contained HTML security report for sharing.
+
+### `rafter issues sync --scan-id <id>`
+
+Open / update GitHub Issues from scan findings (one issue per rule).
+
+### `rafter completion <bash|zsh|fish>`
+
+Emit shell completion script.
+
+---
+
+## Quick Decision Table
+
+| User intent | Command |
+|---|---|
+| Fast secret check locally | `rafter scan local .` |
+| Full repo security review | `rafter run` (then `rafter get <id>`) |
+| "Is this command safe?" | `rafter agent exec --dry-run -- <cmd>` |
+| "Is this skill safe to install?" | `rafter agent audit <path>` |
+| Add pre-commit protection | `rafter agent install-hook` |
+| Wire up CI | `rafter ci init` |
+| Connect an agent | `rafter agent init --with-<platform>` |
+| Share a report | `rafter report --scan-id <id>` |

package/resources/skills/rafter/docs/finding-triage.md

@@ -0,0 +1,79 @@
+# Finding Triage — Reading a Rafter Finding
+
+How to go from a raw Rafter finding to a decision: **fix now**, **fix later**, **suppress**, or **escalate**.
+
+## Anatomy of a Finding
+
+Every finding (local or remote) has this shape:
+
+```jsonc
+{
+  "ruleId": "HARDCODED_API_KEY",       // stable ID — use in overrides / baselines
+  "severity": "critical",               // critical | high | medium | low | info
+  "confidence": "high",                 // high | medium | low
+  "file": "src/config/prod.ts",
+  "line": 42,
+  "title": "Hardcoded API key",
+  "description": "...",
+  "recommendation": "...",              // suggested fix, when available
+  "evidence": "API_KEY = \"sk-...\""    // snippet (may be redacted)
+}
+```
+
+Three fields do most of the work: **severity**, **confidence**, and **ruleId**.
+
+## Decision Flow
+
+1. **Severity `critical` + confidence `high`** → fix before merge. Non-negotiable. Examples: hardcoded production secrets, SQL injection, RCE via unsafe deserialization.
+2. **Severity `high` + confidence `high`** → fix this PR unless there's a specific reason not to (document it in the baseline).
+3. **`high` + confidence `medium/low`** → investigate. Often a real issue in a weird codepath; sometimes a pattern false-positive.
+4. **`medium`** → fix within a reasonable window; batch with related work.
+5. **`low` / `info`** → style/hygiene. Suppress at the rule level if consistently noisy.
+
+Confidence matters: a `high`-severity, `low`-confidence finding is a hypothesis, not a verdict. Confirm by reading the evidence + surrounding code before acting.
+
+## Common Rule Categories
+
+| Rule family | What it means | First move |
+|---|---|---|
+| `HARDCODED_*` (secrets, tokens, keys) | A literal credential is in source | Rotate the credential, then remove from code & git history |
+| `SQL_INJECTION`, `COMMAND_INJECTION` | Unsanitized input reaches a sink | Parameterize / use a safe API; fix at the source, not by escaping at the sink |
+| `INSECURE_DESERIALIZATION` | `pickle`, `yaml.load`, `Marshal`, untrusted JSON → `eval` | Switch to safe loader; never deserialize untrusted data into native objects |
+| `WEAK_CRYPTO` (`MD5`, `SHA1`, `DES`, `ECB`) | Algorithm/mode doesn't meet modern threat model | Swap algorithm; check for backwards-compat constraints |
+| `PATH_TRAVERSAL` | User input flows into filesystem path | Canonicalize + verify within allow-rooted dir |
+| `SSRF` | User input controls outbound URL | Allowlist hosts; resolve IPs and block internal ranges |
+| `DEPENDENCY_CVE` (SCA) | Transitive/direct dep has known CVE | Bump to a patched version; if none, check if the vulnerable code path is reachable |
+
+## Before Rotating or Nuking Something
+
+If the finding is a leaked secret that was committed:
+1. **Rotate first.** Assume the secret is compromised the moment it touched git history.
+2. Remove from history if the repo is private *and* short-lived; otherwise rotation is the real fix.
+3. Add the pattern to pre-commit (`rafter agent install-hook`) so it doesn't happen again.
+
+## Suppression — When It's OK
+
+Suppress only when the finding is a real false positive *for this context*, with a written reason. Two mechanisms:
+
+- **Inline**: `// rafter-ignore: HARDCODED_API_KEY — test fixture, not a real key`
+- **Baseline**: `rafter agent baseline` snapshots current findings; only *new* findings fail future scans. Good for adopting Rafter on a legacy codebase without a big bang.
+
+Never suppress by:
+- Commenting out the rule globally.
+- Broadening an allow-pattern beyond the specific file/context.
+- Deleting the scan step from CI.
+
+## Escalation
+
+Escalate a finding (to security team, or back to the user) when:
+- It implicates production credentials or customer data.
+- It's a design-level issue the local fix can't address (e.g. "the auth model is wrong").
+- The fix requires coordination across services or a rotation playbook.
+
+Provide `scanId`, `ruleId`, file + line, and the evidence snippet. Exit code + JSON makes this a copy-paste to a ticket.
+
+## Tie-Backs
+
+- Want depth on a single finding? Rerun with `--mode plus` (see `docs/backend.md`).
+- Want to prevent the class of finding? See `docs/shift-left.md` → `rafter-secure-design`.
+- Want structured review around the finding? See `docs/shift-left.md` → `rafter-code-review`.