vanara 0.1.0 → 0.3.0

package/catalog/agents/vuln-scanner/examples/scan-report.md

@@ -0,0 +1,49 @@
+# Example: Vulnerability Scan Report
+
+A worked example of the report shape this agent produces. Note the structure: a tight summary, a short
+*fix now* list, then everything else ranked below it. The raw scan had 47 findings; triage reduced the
+release-blocking set to 3.
+
+---
+
+## Summary
+
+- **Scope:** npm dependencies (lockfile), source secret scan, Dockerfile base image.
+- **Findings:** 1 critical, 2 high, 6 medium, 38 low/info (47 raw -> 9 actionable after triage).
+- **Most urgent:** rotate the AWS key committed in `config/legacy.env` — assume compromised.
+
+## Fix now (release-blocking)
+
+| Item | Severity | Fix | Breaking? | Reachability |
+|---|---|---|---|---|
+| AWS access key in `config/legacy.env` | critical | rotate in IAM, move to env var | n/a | Live credential, public history |
+| `lodash@4.17.15` (CVE-2020-8203) | high | -> `4.17.21` | no | Reachable via `util/merge.js` |
+| `axios@0.21.0` (SSRF, CVE-2021-3749) | high | -> `0.21.4` | no | Used in outbound webhook client |
+
+## Plan (schedule, not blocking)
+
+- **`next@12 -> 14` (3 medium CVEs):** breaking major. Clears 3 advisories but requires app-router
+  migration review. Estimate: 1 sprint. Group as one coordinated upgrade.
+- **`debug=true` in `config/prod.json`:** medium. Leaks stack traces to clients; set `false`.
+- **6 transitive medium CVEs in dev-only deps:** real but build-time only; bump opportunistically.
+
+## Exposed secrets
+
+| Secret | Location | Action |
+|---|---|---|
+| AWS access key `AKIA…` | `config/legacy.env:4` | **Rotate** in IAM (revoke old), replace with `AWS_ACCESS_KEY_ID` env var, add pre-commit secret hook |
+| Slack webhook URL | `scripts/notify.sh:12` | Rotate webhook in Slack, move to secret manager |
+
+Removal from the latest commit is **not** sufficient — both are still valid at the provider.
+
+## Config / container risks
+
+- **Base image `node:18.0-alpine`:** carries 4 OS-package CVEs. Bump to current `node:18-alpine` patch.
+- **Container runs as root:** add a non-root `USER` to the Dockerfile.
+
+## Accepted / suppressed (with reason)
+
+- **CVE-2025-XXXX in `fast-xml@3.1.0` (CVSS 9.8):** vulnerable `parseAttrs` path requires
+  `allowAttributes:true`; app uses defaults. Downgraded critical -> medium, scheduled.
+- **`AKIAEXAMPLE…` in `docs/setup.md`:** documentation placeholder, not a live key. Suppressed.
+- **CVE in `jest@…`:** dev/test-only dependency, not in production bundle. Backlog.

package/catalog/agents/vuln-scanner/references/remediation-and-severity.md

@@ -0,0 +1,68 @@
+# Remediation and Severity
+
+Once a finding is triaged, the deliverable is a *fix the reader can act on*. This reference defines the
+severity scale, the dependency-fix strategy, and the secret-rotation playbook.
+
+## Severity scale
+
+Use a single normalized scale across all scan families so the report is comparable:
+
+| Severity | Meaning | Default action |
+|---|---|---|
+| `critical` | Reachable RCE, auth bypass, or active secret leak | Block release; fix now |
+| `high` | Serious impact, exploitable with moderate effort | Fix before release |
+| `medium` | Real but constrained (limited reach or impact) | Schedule next sprint |
+| `low` | Minor / hardening | Backlog |
+| `info` | Awareness only | No action required |
+
+Final severity = scanner severity **adjusted by reachability and impact** (see
+[triage-and-false-positives](triage-and-false-positives.md)). Always show your adjustment reasoning.
+
+## Dependency remediation strategy
+
+For every vulnerable dependency, state the fix version and whether it's breaking:
+
+1. **Prefer the minimal bump that clears the CVE.** If `1.2.3 -> 1.2.4` fixes it, recommend that, not
+   the latest 3.x.
+2. **Label breaking vs. non-breaking** by semver distance and changelog. Crossing a major is breaking
+   until proven otherwise.
+3. **Transitive deps:** if you don't own the dependency directly, fix via the parent bump, or a
+   lockfile override / resolution (`overrides` in npm, `resolutions` in yarn/pnpm) — and flag overrides
+   as a temporary measure, not a permanent pin.
+4. **Group breaking upgrades separately** under *plan* with a migration-risk note. Never bundle a risky
+   major bump into a "quick fix" list.
+5. **No fix available?** Document the mitigation (disable the feature, add input validation, network
+   isolation) and mark for monitoring.
+
+```text
+Fix-now bucket  -> non-breaking bumps that clear critical/high, reachable
+Plan bucket     -> breaking upgrades, lower-severity, or coordinated changes
+Accept/monitor  -> no fix yet, or risk-accepted with justification
+```
+
+## Secret remediation — rotation, not removal
+
+A committed secret is compromised the moment it lands in a shared repo. The fix is always:
+
+1. **Rotate first.** Issue a new credential at the provider and revoke the old one. Until this is done,
+   the secret is live regardless of repo state.
+2. **Remove from code.** Replace with an env var or secret-manager reference.
+3. **Purge from history** if required (history rewrite or, more often, treat as exposed and rely on
+   rotation — rewriting shared history is disruptive and incomplete if the repo was cloned/forked).
+4. **Add prevention.** A pre-commit secret hook and a `.gitignore` entry so it doesn't recur.
+
+> "Deleted the key in the latest commit" is **not** remediation. The credential is still valid at the
+> provider and still present in every prior commit, clone, and CI cache.
+
+## Writing the remediation line
+
+Each finding's recommendation should be copy-pasteable and unambiguous:
+
+```text
+lodash 4.17.15 -> 4.17.21   | high | non-breaking | prototype-pollution CVE-2020-8203, reachable in util/merge.js
+AWS key in config/old.env   | critical | rotate    | revoke in IAM, replace with env var, add pre-commit hook
+debug=true in prod config    | medium | config     | set debug=false; leaks stack traces to clients
+```
+
+Tie remediation effort to severity so the reader can plan: a *fix now* of ten non-breaking bumps is an
+afternoon; one breaking major in *plan* may be a sprint. Make that tradeoff visible.

package/catalog/agents/vuln-scanner/references/scan-types-and-tools.md

@@ -0,0 +1,83 @@
+# Scan Types and Tools
+
+Vulnerability scanning is not one activity — it is a family of complementary techniques, each with a
+different blind spot. A credible scan combines several. Use this reference to pick the right family for
+the target and to understand what each one *cannot* see.
+
+## SCA — Software Composition Analysis (dependency scanning)
+
+Matches your resolved dependency versions against known-vulnerability databases (CVE/NVD, GitHub
+Advisory, OSV).
+
+- **Inputs:** lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `poetry.lock`, `Cargo.lock`, `go.sum`).
+  Always read the **lockfile**, not the manifest range — `^1.2.0` tells you nothing about what shipped.
+- **Strengths:** high-precision for *known* CVEs; cheap; covers transitive deps.
+- **Blind spots:** zero-days, logic bugs, anything not yet in an advisory DB. Version-only matching can
+  over-report (advisory may need a specific feature flag).
+- **Triage hook:** flag direct vs. transitive — a transitive CVE may be fixable only by bumping the
+  parent, or pinning via an override/resolution.
+
+```bash
+# Inventory before judging — never trust the manifest range alone
+node -e "const l=require('./package-lock.json');console.log(Object.keys(l.packages||{}).length,'resolved packages')"
+```
+
+## Secret scanning
+
+Finds credentials committed to the repo: API keys, tokens, private keys, connection strings,
+high-entropy blobs.
+
+- **Inputs:** working tree by default; git history when explicitly requested.
+- **Detection:** known-format regexes (e.g. `AKIA…` AWS keys, `ghp_…` GitHub tokens, `-----BEGIN ...
+  PRIVATE KEY-----`) plus entropy heuristics.
+- **Blind spots:** secrets in untracked files, encrypted blobs, or rotated-but-still-referenced values.
+- **Critical rule:** a found secret is assumed compromised. Removal ≠ remediation. See
+  [remediation-and-severity](remediation-and-severity.md) for the rotation playbook.
+
+```bash
+# Cheap first pass for common key formats (illustrative — a real scan uses a tool)
+grep -rERn 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|-----BEGIN [A-Z ]*PRIVATE KEY-----' . \
+  --include='*.*' || echo "no obvious key-format matches"
+```
+
+## SAST — Static Application Security Testing
+
+Analyzes source/AST for vulnerable patterns: injection sinks, unsafe deserialization, path traversal,
+hardcoded crypto, tainted-data flows.
+
+- **Strengths:** finds bugs in *your* code, not just dependencies; runs without deploying.
+- **Blind spots:** high false-positive rate; struggles with dynamic dispatch and framework magic;
+  cannot judge runtime config.
+- **Triage hook:** SAST output needs the heaviest false-positive filtering. Confirm the sink is
+  reachable with attacker-controlled input before alarming.
+
+## DAST — Dynamic Application Security Testing
+
+Probes a *running* application from the outside: injection, auth handling, misconfigured headers, TLS.
+
+- **Strengths:** finds runtime/config issues SAST can't see; low false positives for what it confirms.
+- **Blind spots:** only covers exercised endpoints; needs a deployed target; can be destructive.
+- **Boundary:** this agent does **not** perform live DAST/exploitation — that is a pen-test activity.
+  Note when DAST is warranted and hand off.
+
+## Container & IaC scanning
+
+When a `Dockerfile`, image, or infra-as-code (Terraform, Kubernetes manifests) is present:
+
+- **Base-image CVEs:** OS packages in the image carry their own advisories; a clean app on a stale base
+  image is still vulnerable.
+- **Image hygiene:** running as root, secrets baked into layers, unpinned `latest` tags.
+- **IaC misconfig:** public S3 buckets, `0.0.0.0/0` security groups, disabled encryption.
+
+## Choosing per target
+
+| Target present | Run | Primary risk caught |
+|---|---|---|
+| Lockfile | SCA | Known CVEs in deps |
+| Any source | Secret scan + SAST | Leaked creds, injection sinks |
+| Dockerfile / image | Container scan | Base-image CVEs, root, baked secrets |
+| Terraform / k8s | IaC scan | Public exposure, weak crypto config |
+| Deployed URL | DAST (hand off) | Runtime/config exploits |
+
+No single family is sufficient. Combine, then triage everything through
+[triage-and-false-positives](triage-and-false-positives.md).

package/catalog/agents/vuln-scanner/references/triage-and-false-positives.md

@@ -0,0 +1,73 @@
+# Triage and False Positives
+
+Triage is the difference between a security agent and a `grep` wrapper. Raw scanner output is a starting
+point with a high noise floor; this reference is how you turn it into signal.
+
+## The triage pipeline
+
+```text
+raw findings
+  -> normalize    (one schema: id, package, severity, location, source-tool)
+  -> dedupe       (same CVE from SCA + container scan = one finding)
+  -> false-positive filter (suppress with a recorded reason)
+  -> reachability assessment (is the vulnerable path used/exposed?)
+  -> final severity (CVSS adjusted by reachability + impact)
+  -> rank + bucket (fix now / plan / accept-monitor)
+```
+
+The bundled `scripts/parse-scan-results.mjs` automates normalize + dedupe + severity sort. Human
+judgment owns the false-positive and reachability steps.
+
+## Deduplication
+
+The same underlying CVE often appears from multiple tools and multiple dependency paths. Collapse them:
+
+- Key on the advisory ID (CVE / GHSA) **plus** the affected package+version.
+- Keep the highest-confidence source and union the locations.
+- Count once in the summary. Reporting one CVE five times manufactures fake urgency and is a form of
+  alert fatigue.
+
+## Identifying false positives
+
+Common false positives and how to confirm them:
+
+| Pattern | Why it's flagged | How to confirm it's benign |
+|---|---|---|
+| Example/placeholder secret | Matches a key regex | Value is `AKIAEXAMPLE…`, in `*.example`, or in test fixtures |
+| Vendored test data | CVE in a bundled sample | Path is under `test/`, `fixtures/`, `__mocks__/` and not shipped |
+| Unreachable CVE | Vulnerable function never called | `grep` for the import/call; if absent, code path is dead |
+| Dev-only dependency | CVE in a build/test tool | Not in production bundle; lower severity, not zero |
+| Feature-gated advisory | Applies only with a flag on | Confirm the flag/default; note the qualifier |
+
+**Always record the suppression reason.** A silently dropped finding is indistinguishable from a missed
+one. Put suppressed items in an "Accepted / suppressed" section with their justification.
+
+## Reachability — the multiplier
+
+Reachability is what separates theoretical from exploitable risk:
+
+- **Exposed + reachable** (e.g. a deserialization CVE on a public POST handler): keep or raise severity.
+- **Present but unreachable** (vulnerable parser never invoked): downgrade, schedule, don't block.
+- **Dev/build-time only:** real but lower; an attacker needs supply-chain or CI access to exploit.
+
+State the reasoning explicitly so a reviewer can overrule:
+
+> CVE-2025-XXXX (CVSS 9.8) in `fast-xml@3.1.0`. The vulnerable `parseAttrs` path is only hit when
+> `allowAttributes:true`; this app calls the parser with defaults. **Downgraded critical -> medium**,
+> scheduled, not release-blocking.
+
+## Avoiding alert fatigue
+
+- Hard-rank. The top finding must be the genuinely most urgent, not the highest raw CVSS.
+- Bucket aggressively: *fix now* should be short (single digits ideally). Everything else goes to
+  *plan* or *accept/monitor*.
+- Push low/info findings into an appendix. Do not make a reader scroll past 200 lows to find the one
+  critical — that is how real issues get missed.
+- Be consistent run-to-run so developers can diff reports and see what's new.
+
+## When triage is genuinely uncertain
+
+If you cannot determine reachability from static analysis alone, say so and assign provisional severity
+on the conservative side, with a note on what would resolve the uncertainty (e.g. "needs DAST against
+staging" or "confirm whether `module X` is in the production bundle"). Honest uncertainty beats false
+confidence in either direction.

package/catalog/agents/vuln-scanner/scripts/parse-scan-results.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Normalizes a list of raw vulnerability findings: dedupes and sorts by
+// triaged severity. Demonstrates the triage step (raw output -> ranked list)
+// from this agent package. Zero dependencies; Node built-ins only.
+//
+// Usage:
+//   node parse-scan-results.mjs findings.json     # read a JSON array from a file
+//   cat findings.json | node parse-scan-results.mjs   # read from stdin
+//   node parse-scan-results.mjs --selftest        # run built-in tests (exit 0/1)
+//
+// Input: JSON array of findings, each with at least { id, severity }.
+// Optional fields: package, location, cvss, reachability, fix, bucket.
+// Output: { total, deduped, bySeverity, findings } sorted critical -> info.
+
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
+const SEVERITY_RANK = Object.fromEntries(SEVERITY_ORDER.map((s, i) => [s, i]));
+
+function normalizeSeverity(sev) {
+  const s = String(sev ?? '').toLowerCase().trim();
+  return SEVERITY_RANK[s] !== undefined ? s : 'info';
+}
+
+// Dedup key: advisory id + affected package/location. The same CVE reported by
+// multiple tools or via multiple paths collapses to one finding.
+function dedupKey(f) {
+  const id = String(f.id ?? 'unknown').toLowerCase();
+  const where = String(f.package ?? f.location ?? '').toLowerCase();
+  return `${id}::${where}`;
+}
+
+export function parseFindings(rawList) {
+  if (!Array.isArray(rawList)) {
+    throw new Error('input must be a JSON array of findings');
+  }
+
+  const seen = new Map();
+  for (const raw of rawList) {
+    const finding = { ...raw, severity: normalizeSeverity(raw.severity) };
+    const key = dedupKey(finding);
+    if (!seen.has(key)) {
+      seen.set(key, finding);
+    } else {
+      // Keep the higher severity when duplicates disagree.
+      const existing = seen.get(key);
+      if (SEVERITY_RANK[finding.severity] < SEVERITY_RANK[existing.severity]) {
+        seen.set(key, finding);
+      }
+    }
+  }
+
+  const findings = [...seen.values()].sort((a, b) => {
+    const d = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    if (d !== 0) return d;
+    return String(a.id ?? '').localeCompare(String(b.id ?? ''));
+  });
+
+  const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
+  for (const f of findings) bySeverity[f.severity] += 1;
+
+  return { total: rawList.length, deduped: findings.length, bySeverity, findings };
+}
+
+function run(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    console.error('✗ invalid JSON input');
+    process.exit(1);
+  }
+  try {
+    const result = parseFindings(parsed);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function selftest() {
+  const raw = [
+    { id: 'CVE-1', package: 'lodash@4.17.15', severity: 'high' },
+    { id: 'CVE-1', package: 'lodash@4.17.15', severity: 'medium' }, // dup, lower sev
+    { id: 'CVE-2', package: 'axios@0.21.0', severity: 'CRITICAL' },  // case-insensitive
+    { id: 'CVE-3', package: 'jest@29', severity: 'low' },
+    { id: 'SECRET-1', location: 'config/x.env', severity: 'critical' },
+    { id: 'CVE-4', package: 'debug@4', severity: 'weird' },          // -> info
+  ];
+
+  const result = parseFindings(raw);
+  const checks = [];
+
+  // Dedup: 6 raw -> 5 unique (the two CVE-1 collapse).
+  checks.push(['dedupes duplicates', result.total === 6 && result.deduped === 5]);
+
+  // Duplicate keeps the higher severity (high, not medium).
+  const cve1 = result.findings.find((f) => f.id === 'CVE-1');
+  checks.push(['dup keeps higher severity', cve1 && cve1.severity === 'high']);
+
+  // Severity counts after normalization.
+  checks.push(['critical count is 2', result.bySeverity.critical === 2]);
+  checks.push(['high count is 1', result.bySeverity.high === 1]);
+  checks.push(['unknown severity -> info', result.bySeverity.info === 1]);
+
+  // Sort order: criticals first, info last.
+  const order = result.findings.map((f) => f.severity);
+  const sorted = [...order].sort(
+    (a, b) => SEVERITY_RANK[a] - SEVERITY_RANK[b]
+  );
+  checks.push(['sorted by severity', JSON.stringify(order) === JSON.stringify(sorted)]);
+  checks.push(['first finding is critical', order[0] === 'critical']);
+  checks.push(['last finding is info', order[order.length - 1] === 'info']);
+
+  let ok = true;
+  for (const [label, passed] of checks) {
+    console.log(`${passed ? '✓' : '✗'} ${label}`);
+    ok &&= passed;
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  const { readFileSync } = await import('node:fs');
+  run(readFileSync(arg, 'utf8'));
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => run(buf));
+}

package/catalog/packs/code-review-pack/PACK.md

@@ -0,0 +1,100 @@
+---
+name: code-review-pack
+description: Review pull requests faster and better — automated first-pass review, PR summaries reviewers can trust, healthy git workflow settings, conventional history, and query-performance checks, sequenced into one review pipeline.
+type: pack
+version: 1.0.0
+updated: 2026-07-10
+agents: [code-reviewer, pr-summarizer]
+skills: [git-collaboration-workflows, conventional-commits, sql-index-tuning]
+---
+# Code Review Pack
+
+The review toolkit for teams whose bottleneck is the pull-request queue: get every PR a
+fast, rigorous first pass, give human reviewers a summary they can trust, and keep the
+workflow settings and history hygiene that make review scale. The value of the pack is the
+**sequence** — which item runs at which moment of a PR's life — not the item list.
+
+## Who this is for
+
+Teams merging more PRs than their senior reviewers can deeply read; leads who want review
+latency down without review quality collapsing; anyone inheriting a repo where "review"
+means LGTM-stamping.
+
+## What's included
+
+- **Agents:** `code-reviewer` (rigorous first-pass review: correctness, security, tests,
+  maintainability), `pr-summarizer` (what changed, why, risk areas — the reviewer's map).
+- **Skills:** `git-collaboration-workflows` (branch protection, PR sizing, merge strategy,
+  monorepo questions), `conventional-commits` (machine-readable history that powers
+  changelogs and bisect), `sql-index-tuning` (the query-performance review lens most teams
+  lack — N+1s and missing indexes are the top silent regressions PRs ship).
+
+## The review pipeline (how the pieces sequence)
+
+```text
+PR opened
+  1. pr-summarizer     → posts the map: what changed, why, blast radius, files to read first
+  2. code-reviewer     → first-pass findings: blocking / question / nit, with file:line
+       └─ SQL touched? → sql-index-tuning lens: EXPLAIN the new queries, check indexes
+  3. human reviewer    → reads the summary + findings, spends attention ONLY on judgment
+                         calls the machine flagged and the design questions it can't make
+merge
+  4. conventional-commits → squash message feeds changelog + bisect-friendly history
+weekly
+  5. git-collaboration-workflows → hygiene audit: branch age, PR size trend, protection drift
+```
+
+The division of labor is the point: agents do coverage (every line, every time), humans do
+judgment (architecture, product fit, taste). Teams that flip this — humans doing coverage,
+no machine pass — get slow reviews AND missed bugs.
+
+## Setup
+
+1. Install the pack; wire `pr-summarizer` + `code-reviewer` to run on PR-open (CI job or
+   scheduled agent).
+2. Apply the branch-protection settings from `git-collaboration-workflows`
+   (`examples/branch-protection.md`) — required checks, stale-review dismissal, squash-only.
+3. Adopt the `blocking:/q:/nit:` comment convention from the PR review playbook; announce
+   the review SLO (first response < 4h).
+4. Enable commit-lint per `conventional-commits` so the history contract is enforced, not
+   hoped for.
+
+## Comment convention (adopt verbatim)
+
+```text
+blocking:  must be fixed before merge — correctness, security, data loss
+q:         genuine question; answer may resolve it
+nit:       author's call; NEVER blocks
+(unprefixed comments read as blocking — prefix everything)
+```
+
+## Pitfalls
+
+- **LGTM-stamping past machine findings** — the pipeline's failure mode; blocking findings
+  must actually block, or reverts won't move.
+- **Bot-nit fatigue** — untuned severity turns the first-pass reviewer into noise; demote
+  misfiring rules weekly during rollout (see `references/rollout-guide.md`).
+- **Summaries as gospel on giant PRs** — a wrong map on a 2,000-line PR is an argument for
+  the size norms, not against the mapper.
+- **Skipping the SQL lens** — missing-index regressions pass every test and fail at the
+  10× tenant; the `EXPLAIN` step is not optional when queries change.
+- **Anti-pattern: humans doing coverage** — re-reading every line the machine read wastes
+  the scarce resource (judgment) on the abundant one (attention).
+
+## When NOT to use this shape
+
+Solo projects (review theater), and rubber-stamp compliance environments where findings
+can't block merges anyway — fix the process authority first, then install tooling.
+Edge case worth naming: generated code and vendored files should be excluded from both
+summary and review scope up front, or they drown every real finding.
+
+## Verification
+
+After two weeks, three numbers should move: median time-to-first-review (down), PR size p50
+(down — the summary+size norms push authors to split), and post-merge defect
+reverts (down). If reverts didn't move, check whether `code-reviewer` findings are being
+LGTM'd past — the pipeline only works when blocking findings block. A full worked PR
+walkthrough lives in [examples/pr-flow-example.md](examples/pr-flow-example.md).
+
+Pairs with the `secure-delivery-pack` (security-focused review lenses) and
+`craftsmanship-pack` (refactoring and test depth beyond the review gate).

package/catalog/packs/code-review-pack/examples/pr-flow-example.md

@@ -0,0 +1,50 @@
+# Worked Example — one PR through the pipeline
+
+PR #512: "Add invoice CSV export" — 380 lines, touches API + a new query + one UI table.
+
+## 1. pr-summarizer posts (2 min after open)
+
+> **What**: New `GET /invoices/export.csv` endpoint (streaming), export button on the
+> invoices table, `invoices_export` permission.
+> **Why**: FEAT-201 — finance team needs monthly exports.
+> **Read first**: `export-controller.ts` (new query!), `permissions.ts` (auth change).
+> **Blast radius**: read-only endpoint; new DB query on `invoices` (potentially large);
+> no schema change. **Risk**: memory on large exports, query performance.
+
+## 2. code-reviewer posts (5 min after open)
+
+> `blocking:` export-controller.ts:41 — query selects `*` and loads all rows into memory
+> before streaming; a 500k-invoice tenant OOMs the pod. Stream with a cursor
+> (keyset pagination) or use the DB driver's row stream.
+>
+> `blocking:` export-query.sql — `WHERE tenant_id = ? AND created_at > ?` has no
+> supporting composite index (per sql-index-tuning: needs `(tenant_id, created_at)`;
+> current plan is a seq scan at 2M rows — EXPLAIN attached).
+>
+> `q:` permissions.ts:88 — `invoices_export` granted to `member` by default; FEAT-201
+> says finance-only. Intended?
+>
+> `nit:` csv column headers hardcoded English — project is i18n'd (`internationalization`).
+
+## 3. Human reviewer (18 min later, reads summary + findings first)
+
+Spends attention on the two judgment calls: confirms permission should be finance-only
+(product check), and decides streaming approach (driver row-stream over keyset — simpler
+here). Doesn't re-read the 300 lines the machine already covered line-by-line; spot-checks
+the test file.
+
+## 4. Author revises → checks green → squash-merge
+
+```text
+feat(invoices): add streaming CSV export (FEAT-201)
+
+Finance-only permission; keyset-cursor streaming; composite index
+(tenant_id, created_at) added expand-only.
+```
+
+## Outcome ledger
+
+- OOM prevented pre-merge (would have been a Sev-2 at month-end).
+- Missing index caught before it met the 2M-row tenant.
+- Human review time: ~20 min for a 380-line PR, spent entirely on judgment.
+- History entry supports changelog + bisect.

package/catalog/packs/code-review-pack/references/rollout-guide.md

@@ -0,0 +1,40 @@
+# Rollout Guide
+
+Review culture changes fail when imposed all at once. The two-week sequence that lands:
+
+## Week 1 — observation mode
+
+- Wire `pr-summarizer` only. Zero friction, immediate value: every PR gets a map. Nobody
+  argues with a summary.
+- Run `code-reviewer` in **comment-only** mode (findings posted, nothing blocks). The team
+  calibrates trust: are the findings real? (Tune severity thresholds now, while stakes are
+  low.)
+- Baseline the three metrics: time-to-first-review, PR size p50, revert rate. You need the
+  "before" or the "after" is a vibe.
+
+## Week 2 — the contract
+
+- Turn on branch protection per the skill's settings (checks required, stale-dismissal,
+  squash-only). Announce it as config, with the escape hatch documented (hotfix label path).
+- Adopt comment prefixes (`blocking:/q:/nit:`) and the 4-hour first-response SLO — put the
+  SLO on a dashboard where standup sees it.
+- commit-lint on (warning for 3 days, then required).
+
+## Weeks 3+ — enforcement earned
+
+- `code-reviewer` blocking findings now actually block (the team has seen two weeks of its
+  judgment; false-positive rate is known and tuned).
+- Weekly hygiene audit (`check-branch-hygiene.mjs`) posted to the team channel — trends,
+  not blame.
+
+## Objection handling (you will hear these)
+
+- **"The bot nitpicks."** Nits never block — that's what the prefix system encodes. Tune or
+  demote rules that misfire; the config is code-reviewable.
+- **"Summaries are wrong sometimes."** They're maps, not territory — a wrong summary on a
+  2,000-line PR is an argument for smaller PRs, which the size norms fix.
+- **"This slows us down."** The SLO + protection settings measurably speed up the queue;
+  show the week-1 baseline vs week-4. What slows teams is review latency and re-review
+  churn, both of which drop.
+- **"Admins need bypass."** The bypass IS the vulnerability; the hotfix path exists and is
+  faster than arguing at 2 a.m.