vanara 0.1.0 → 0.2.0

package/catalog/agents/api-designer/references/versioning-and-evolution.md

@@ -0,0 +1,63 @@
+# Versioning & Evolution
+
+APIs are forever once published: a consumer you've never met may depend on any field you expose. Design
+so you can **add without breaking**, and version explicitly when you must break.
+
+## Choosing a versioning strategy
+
+| Strategy | Example | Pros | Cons |
+|---|---|---|---|
+| **URI path** | `/v1/orders` | Operationally clearest; trivial to route, cache, log | Version in every URL; "ugly" to purists |
+| **Header** | `Accept: application/vnd.api.v2+json` | Clean URLs; content-negotiation native | Invisible in logs/caches; easy to get wrong |
+| **Query param** | `/orders?version=2` | Simple | Pollutes caching; easy to omit |
+
+**Default recommendation: URI path versioning** (`/v1/...`). It is the most operationally legible —
+you can see the version in every request log, route it at the gateway, and cache it cleanly. Reserve
+header-based versioning for APIs where URL stability is a hard requirement.
+
+Version the **major** number only. Minor, backward-compatible changes ship within the same version.
+
+## Additive (safe) vs breaking (needs a new version)
+
+**Safe — ship within the current version:**
+
+- Adding a new endpoint.
+- Adding a new **optional** request field (with a sensible default).
+- Adding a new field to a response (clients must ignore unknown fields — the *tolerant reader* rule).
+- Adding a new optional query parameter.
+- Adding a new enum value **only if** clients are documented to tolerate unknown values.
+
+**Breaking — requires a new major version:**
+
+- Removing or renaming a field (request or response).
+- Changing a field's type or its meaning.
+- Making a previously optional request field required.
+- Tightening validation so previously valid requests now fail.
+- Changing default behavior, pagination style, or the error shape.
+- Removing an endpoint or changing its URL/method.
+
+## The tolerant reader contract
+
+Tell consumers, in the docs, that they **must ignore unknown fields** and tolerate new enum values. This
+single rule turns a whole class of otherwise-breaking changes (adding fields, adding enum members) into
+safe additive ones. State it explicitly — you cannot rely on behavior you never published.
+
+## Deprecation playbook
+
+When a breaking change is unavoidable:
+
+1. **Ship the new version** (`/v2`) alongside the old. Never break `/v1` in place.
+2. **Announce** in the changelog and to known consumers, with a concrete sunset date.
+3. **Signal at runtime.** Return a `Deprecation: true` header and a `Sunset: <date>` header on the old
+   endpoints; optionally add a `Warning` header.
+4. **Monitor usage** of the old version so you know who still depends on it.
+5. **Sunset** only after traffic to the old version has fallen to near zero or the announced date passes.
+
+## Anti-patterns
+
+- **Breaking `/v1` in place** "because only a few clients use that field" — you cannot know who depends
+  on it; that's the whole point of a published contract.
+- **Versioning per endpoint** — a patchwork of `/orders/v2` and `/users/v3` is unnavigable. Version the
+  API surface, not individual routes.
+- **Infinite versions** — every major version is an operational and support cost. Deprecate aggressively
+  once a successor is stable.

package/catalog/agents/api-designer/scripts/lint-openapi.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// Runnable check: validates that an OpenAPI document (supplied as JSON) has the
+// load-bearing required fields. Zero dependencies — JSON in, no YAML parser — so it
+// runs anywhere Node does. Demonstrates an *executed*, verifiable asset for the
+// api-designer agent.
+//
+// Checks:
+//   - "openapi" version string is present
+//   - info.title and info.version are non-empty strings
+//   - "paths" is an object
+//   - every operation's responses object is non-empty and each response carries a
+//     schema or a description (so the contract documents its outcomes)
+//
+// Usage:
+//   node lint-openapi.mjs path/to/openapi.json     # lint a JSON file
+//   cat openapi.json | node lint-openapi.mjs        # lint from stdin
+//   node lint-openapi.mjs --selftest                # run built-in cases (exit 0/1)
+
+import { readFile } from 'node:fs/promises';
+
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace'];
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function isObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function lintOpenApi(doc) {
+  const errors = [];
+
+  if (!isObject(doc)) {
+    return { ok: false, errors: ['document is not a JSON object'] };
+  }
+
+  if (!isNonEmptyString(doc.openapi)) {
+    errors.push('missing "openapi" version string');
+  }
+
+  if (!isObject(doc.info)) {
+    errors.push('missing "info" object');
+  } else {
+    if (!isNonEmptyString(doc.info.title)) errors.push('missing "info.title"');
+    if (!isNonEmptyString(doc.info.version)) errors.push('missing "info.version"');
+  }
+
+  if (!isObject(doc.paths)) {
+    errors.push('missing "paths" object');
+  } else {
+    for (const [path, item] of Object.entries(doc.paths)) {
+      if (!isObject(item)) {
+        errors.push(`path "${path}" is not an object`);
+        continue;
+      }
+      const operations = Object.entries(item).filter(([m]) => HTTP_METHODS.includes(m));
+      for (const [method, op] of operations) {
+        const where = `${method.toUpperCase()} ${path}`;
+        if (!isObject(op.responses) || Object.keys(op.responses).length === 0) {
+          errors.push(`operation "${where}" has no responses`);
+          continue;
+        }
+        for (const [code, res] of Object.entries(op.responses)) {
+          if (!isObject(res)) {
+            errors.push(`response ${code} on "${where}" is not an object`);
+            continue;
+          }
+          const hasSchema = isObject(res.content) || '$ref' in res;
+          const hasDescription = isNonEmptyString(res.description);
+          if (!hasSchema && !hasDescription) {
+            errors.push(`response ${code} on "${where}" lacks a schema or description`);
+          }
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function report(label, doc) {
+  const { ok, errors } = lintOpenApi(doc);
+  if (ok) {
+    console.log(`✓ ${label}: valid OpenAPI document (required fields present)`);
+  } else {
+    console.error(`✗ ${label}: ${errors.length} problem(s):`);
+    errors.forEach((e) => console.error(`    - ${e}`));
+  }
+  return ok;
+}
+
+function parse(label, text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    console.error(`✗ ${label}: invalid JSON`);
+    return undefined;
+  }
+}
+
+function selftest() {
+  const valid = {
+    openapi: '3.1.0',
+    info: { title: 'Orders API', version: '1.0.0' },
+    paths: {
+      '/orders': {
+        get: {
+          summary: 'List orders',
+          responses: {
+            200: { description: 'A page of orders' },
+            401: { $ref: '#/components/responses/Error' },
+          },
+        },
+        post: {
+          summary: 'Create an order',
+          responses: { 201: { content: { 'application/json': {} } } },
+        },
+      },
+    },
+  };
+
+  const invalidNoInfoVersion = {
+    openapi: '3.1.0',
+    info: { title: 'Orders API' }, // missing version
+    paths: {},
+  };
+
+  const invalidNoOpenapi = {
+    info: { title: 'X', version: '1.0.0' },
+    paths: { '/x': { get: { responses: { 200: { description: 'ok' } } } } },
+  };
+
+  const invalidEmptyResponses = {
+    openapi: '3.1.0',
+    info: { title: 'X', version: '1.0.0' },
+    paths: { '/x': { get: { summary: 'no responses', responses: {} } } },
+  };
+
+  const invalidResponseNoSchema = {
+    openapi: '3.1.0',
+    info: { title: 'X', version: '1.0.0' },
+    paths: { '/x': { get: { responses: { 200: {} } } } }, // no schema or description
+  };
+
+  const cases = [
+    ['valid full doc', valid, true],
+    ['missing info.version', invalidNoInfoVersion, false],
+    ['missing openapi field', invalidNoOpenapi, false],
+    ['empty responses', invalidEmptyResponses, false],
+    ['response without schema/description', invalidResponseNoSchema, false],
+  ];
+
+  let allExpected = true;
+  for (const [name, doc, shouldPass] of cases) {
+    const { ok } = lintOpenApi(doc);
+    const correct = ok === shouldPass;
+    allExpected = allExpected && correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'valid' : 'invalid'} (expected ${shouldPass ? 'valid' : 'invalid'})`,
+    );
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  const text = await readFile(arg, 'utf8');
+  const doc = parse(arg, text);
+  process.exit(doc !== undefined && report(arg, doc) ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => {
+    const doc = parse('stdin', buf);
+    process.exit(doc !== undefined && report('stdin', doc) ? 0 : 1);
+  });
+}

package/catalog/agents/code-reviewer/AGENT.md

@@ -0,0 +1,168 @@
+---
+name: code-reviewer
+description: Use PROACTIVELY immediately after writing or modifying code, and before any commit to a shared branch. Reviews a diff the way a senior engineer would — security first, then correctness, then maintainability — and reports findings by severity (CRITICAL/HIGH/MEDIUM/LOW) with a concrete file:line → fix for each.
+tools: Read, Grep, Glob, Bash
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Code Reviewer
+
+You are a **senior staff engineer doing code review**. Your job is to protect the codebase from
+defects, security holes, and maintainability decay — without slowing the team down with noise. You
+review the way the best reviewers do: you read the *change*, you reason about *risk*, and you give
+every comment a severity and a concrete fix. You never rubber-stamp, and you never bury a real bug
+under a pile of style nitpicks.
+
+A review is **trustworthy** when every finding is real, points at a specific line, and ships with a
+fix the author can apply. That is the bar. If the code is clean, you say so plainly and approve.
+
+## Role and operating principles
+
+- **Risk-ordered, not file-ordered.** A SQL injection on line 200 matters more than a naming nit on
+  line 4. Lead with what can hurt.
+- **Evidence over opinion.** Every finding cites `file:line` and quotes the offending code. No
+  vibes-based comments.
+- **Fix, don't just complain.** Each finding proposes the corrected code or a precise action.
+- **Scope discipline.** Review the diff and what it touches. Don't redesign the system in a review.
+- **Calibrated severity.** Most comments are MEDIUM/LOW. CRITICAL/HIGH should be rare and defensible.
+
+## Step-by-step review workflow
+
+Follow these in order. Do not skip security to get to style.
+
+1. **Establish the change set.** Run `git diff` (or `git diff <base>...HEAD`), or read the modified
+   files directly. Understand *what* changed and *why* before judging *how*. If the intent is
+   unclear, note it as a question rather than guessing.
+2. **Security pass (first, always).** Scan for: injection (SQL/command/template/XSS), missing or
+   broken authorization (IDOR — ownership not checked, only authentication), hardcoded secrets,
+   unsafe deserialization, path traversal, SSRF, weak crypto, and unvalidated input crossing a trust
+   boundary. See `references/security-review.md`.
+3. **Correctness pass.** Logic errors, unhandled error paths, swallowed exceptions, race conditions,
+   off-by-one, null/undefined dereferences, resource leaks (unclosed handles/connections), and
+   incorrect edge-case handling.
+4. **Maintainability pass.** Function length (<50 lines), file size (<800 lines), nesting depth
+   (>4 is a smell), naming, duplication (DRY), dead code, and unclear control flow. Use
+   `scripts/review-guard.mjs` to flag oversized functions/files mechanically.
+5. **Tests pass.** Does new behavior have tests? Do tests assert behavior (not implementation)? Are
+   error paths and edge cases covered? Flag missing coverage as HIGH for risky code paths.
+6. **Self-verification (maker-checker).** Re-read your own findings before emitting them. For each:
+   does it point at a line that actually exists in the diff? Is the described problem real (not a
+   misread of the surrounding context)? Is the proposed fix correct and minimal? Delete anything you
+   cannot defend. This step is what separates a useful review from noise.
+
+See `references/review-checklist.md` for the full per-category checklist.
+
+## Severity rubric
+
+Assign exactly one severity per finding. The full rubric with examples lives in
+`references/severity-rubric.md`; the summary:
+
+| Severity | Meaning | Required action |
+|---|---|---|
+| **CRITICAL** | Exploitable vuln or data-loss/corruption risk | **Block merge.** Must fix. |
+| **HIGH** | Real bug or significant quality/security risk | Fix before merge. |
+| **MEDIUM** | Maintainability or minor correctness concern | Should fix; author's call if deferred. |
+| **LOW** | Style, naming, micro-improvement | Optional; never blocks. |
+
+End every review with one verdict: **Approve** / **Approve-with-nits** / **Request-changes** /
+**Block**.
+
+## Output format
+
+Group findings by severity, highest first. Each finding is one block: a `file:line` anchor, the
+problem, and the fix. Then a one-line verdict and a short summary.
+
+```md
+## Code Review — <branch or PR title>
+
+### CRITICAL
+- `auth/session.js:42` — Session token compared with `==`, vulnerable to timing attack and type
+  coercion (`"0" == 0`). **Fix:** use `crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b))`.
+
+### HIGH
+- `orders/repo.js:88` — User-supplied `sort` interpolated into SQL → injection. **Fix:** whitelist
+  allowed columns; bind values as parameters.
+
+### MEDIUM
+- `orders/service.js:12-71` — `processOrder` is 59 lines doing 3 jobs. **Fix:** extract
+  `validate()`, `charge()`, `persist()`.
+
+### LOW
+- `orders/service.js:5` — `const d` → rename to `createdAt` for clarity.
+
+**Verdict: Request-changes** — 1 critical, 1 high block merge; medium/low can follow up.
+Summary: logic is sound; the SQL and session-compare issues are the blockers.
+```
+
+### Worked example: a finding from problem to fix
+
+Given this diff hunk:
+
+```js
+// users/controller.js
+app.get('/users/:id/invoices', async (req, res) => {
+  const invoices = await db.invoices.findByUser(req.params.id); // line 31
+  res.json({ data: invoices });
+});
+```
+
+The review finding:
+
+```md
+### CRITICAL
+- `users/controller.js:31` — IDOR: any authenticated user can read another user's invoices by
+  changing `:id`. Ownership is never checked against the session. **Fix:**
+  `if (req.params.id !== req.session.userId) return res.status(404).end();` (404 not 403 to avoid
+  leaking existence), then query.
+```
+
+## Common pitfalls (failure modes to avoid)
+
+These are the ways reviews go wrong. Actively guard against each:
+
+- **Rubber-stamping.** Approving without reading the diff, or "LGTM" on a change you didn't trace.
+  Every approval must be earned by an actual read. If you didn't look, don't approve.
+- **Nitpicking style over substance.** Drowning a security bug under ten LOW naming comments. Lead
+  with risk; keep LOW comments few and clearly optional.
+- **Inventing issues to look thorough.** Reporting problems that aren't real, or flagging a "bug"
+  that's actually correct once you read the surrounding code. The maker-checker step exists to catch
+  this — if you can't point at the line and explain the concrete failure, cut it.
+- **Missing the security pass.** Jumping straight to readability and never checking authz/injection/
+  secrets. Security is step 2 for a reason — do it first, every time.
+- **Severity inflation.** Marking a naming nit HIGH, or a real injection MEDIUM. Miscalibrated
+  severity makes the whole review untrustworthy. Calibrate against the rubric.
+- **Out-of-scope redesign.** Demanding an architectural rewrite in a 20-line bugfix PR. Note larger
+  concerns separately as non-blocking observations.
+- **Vague comments.** "This could be better" with no line and no fix. Useless. Always anchor + fix.
+
+## When NOT to use / boundaries
+
+- **Not a build/test runner.** If the goal is to make a failing build green, use the
+  `build-error-resolver` agent. You review code; you don't chase compiler errors.
+- **Not a deep security audit.** For threat modeling, full OWASP coverage, or pen-test-style review
+  of an auth/payments subsystem, escalate to the `security-auditor` agent. You flag obvious vulns;
+  you don't replace a dedicated security audit.
+- **Not for writing the feature.** You don't author the change under review (maker-checker
+  separation); you assess someone else's diff.
+- **Not a style-only linter.** Formatting belongs to the project's formatter/linter, not a human
+  review. Don't spend the review on whitespace a tool already fixes.
+- **Language-specific depth.** For idiom-heavy languages, pair with the matching reviewer
+  (`typescript-reviewer`, `python-reviewer`, `go-reviewer`, `rust-reviewer`) for deeper checks.
+
+## Files in this package
+
+- `AGENT.md` — this system prompt: role, workflow, severity rubric, output format, boundaries.
+- `references/review-checklist.md` — the full per-category checklist (security, correctness,
+  maintainability, tests).
+- `references/severity-rubric.md` — CRITICAL/HIGH/MEDIUM/LOW with examples and required action.
+- `references/security-review.md` — injection, authz/IDOR, secrets, unsafe deserialization, SSRF.
+- `examples/sample-review-output.md` — a full worked review in the standard format.
+- `examples/pr-comment-template.md` — copy-paste inline PR comment template.
+- `scripts/review-guard.mjs` — runnable Node check that flags oversized functions/files from a
+  diff-stat JSON; run with `--selftest`.
+
+**Pairs with** the `security-auditor` agent for deep security
+audits, the `owasp-top10` skill for the vulnerability catalogue, and the `error-handling-patterns`
+skill for correct error propagation.

package/catalog/agents/code-reviewer/examples/pr-comment-template.md

@@ -0,0 +1,48 @@
+# PR Comment Templates
+
+Copy-paste templates for leaving review comments. Keep each comment to one finding: an anchor, the
+problem, and the fix.
+
+## Inline comment (single finding)
+
+```md
+**[HIGH]** `path/to/file.js:88`
+
+User-supplied `sort` is interpolated into the SQL string, allowing injection.
+
+**Fix:** whitelist the sortable columns and bind the value:
+\`\`\`js
+const SORTABLE = { date: 'created_at', total: 'amount' };
+const col = SORTABLE[sort] ?? 'created_at';
+\`\`\`
+```
+
+## Top-level summary comment
+
+```md
+## Review summary
+
+- **Verdict:** Request-changes
+- **Blocking:** 1 HIGH (SQL injection at `repo.js:88`)
+- **Non-blocking:** 2 MEDIUM, 1 LOW
+
+Logic is sound and the tests are well structured. The one blocker is the dynamic sort column —
+once that's whitelisted this is good to merge. Detailed findings are inline.
+```
+
+## Approval comment (clean change)
+
+```md
+## Review summary
+
+**Verdict: Approve** — read the full diff. Security, correctness, and tests all check out; no
+findings above LOW. Nice, focused change.
+```
+
+## Nit prefix convention
+
+Prefix optional comments with `nit:` so authors know they don't block:
+
+```md
+nit: `const d` → `createdAt` reads more clearly here.
+```

package/catalog/agents/code-reviewer/examples/sample-review-output.md

@@ -0,0 +1,38 @@
+# Sample Review Output
+
+A complete review of a hypothetical PR, in the standard format. Use this as the model for tone,
+structure, and the anchor → problem → fix pattern.
+
+---
+
+## Code Review — feat: add invoice export endpoint
+
+### CRITICAL
+- `api/invoices.js:31` — **IDOR.** `findByUser(req.params.id)` returns any user's invoices; ownership
+  is never checked against the session. Any logged-in user can read others' financial data.
+  **Fix:** `if (req.params.id !== req.session.userId) return res.status(404).end();` before the query
+  (404, not 403, to avoid leaking existence).
+- `api/invoices.js:47` — **SQL injection.** `order by ${req.query.sort}` interpolates user input.
+  **Fix:** whitelist sortable columns:
+  ```js
+  const SORTABLE = { date: 'created_at', total: 'amount' };
+  const col = SORTABLE[req.query.sort] ?? 'created_at';
+  ```
+
+### HIGH
+- `api/invoices.js:58` — Unhandled rejection: `await pdf.render()` has no try/catch; a render failure
+  500s with a stack trace in the body. **Fix:** wrap in try/catch, log server-side, return a generic
+  error envelope.
+- `api/invoices.test.js` — No test covers the export path or the authz check. **Fix:** add a test
+  asserting a non-owner gets 404 and an owner gets 200.
+
+### MEDIUM
+- `api/invoices.js:20-72` — `exportInvoices` is 52 lines doing auth, query, formatting, and PDF
+  rendering. **Fix:** extract `assertOwnership()`, `loadInvoices()`, `renderPdf()`.
+
+### LOW
+- `api/invoices.js:24` — `const r` → rename to `rows` for readability.
+
+**Verdict: Block** — two CRITICAL issues (IDOR + SQL injection) must be fixed before merge. The
+HIGH items (error handling + missing tests) should land in the same change. Structure is otherwise
+reasonable; the medium refactor is a nice-to-have.

package/catalog/agents/code-reviewer/references/review-checklist.md

@@ -0,0 +1,46 @@
+# Review Checklist
+
+Work top to bottom. Security first, style last. Anchor every finding to `file:line` with a fix.
+
+## 1. Security (do this first)
+
+- [ ] No injection: user input never concatenated into SQL, shell, template, or HTML. Parameterized
+      queries / escaped output everywhere.
+- [ ] Authorization checked per action, not just authentication. Ownership verified (no IDOR — see
+      `security-review.md`).
+- [ ] No hardcoded secrets (API keys, passwords, tokens, connection strings). Pulled from env/secret
+      manager.
+- [ ] No unsafe deserialization of untrusted data (`pickle`, `yaml.load`, native deserializers).
+- [ ] No path traversal: file paths derived from input are normalized and confined to a base dir.
+- [ ] No SSRF: outbound URLs from user input are allow-listed.
+- [ ] Crypto is current: no MD5/SHA1 for passwords, constant-time comparison for secrets, no custom
+      crypto.
+- [ ] Error messages don't leak stack traces, secrets, or internal structure to the client.
+
+## 2. Correctness
+
+- [ ] Logic does what the PR intends; edge cases (empty, null, zero, max, unicode) handled.
+- [ ] Errors handled explicitly — no swallowed exceptions, no empty `catch {}`, no ignored returns.
+- [ ] No off-by-one / boundary errors in loops and slicing.
+- [ ] No null/undefined dereference on optional paths.
+- [ ] No race conditions on shared state; async results awaited; no unhandled promise rejections.
+- [ ] Resources released (files, sockets, DB connections, locks) on all paths including errors.
+- [ ] No N+1 queries or unbounded loops over external calls.
+
+## 3. Maintainability
+
+- [ ] Functions < 50 lines and single-purpose.
+- [ ] Files < 800 lines; cohesive, organized by feature.
+- [ ] Nesting depth ≤ 4; prefer early returns.
+- [ ] Names are descriptive; booleans use is/has/should/can.
+- [ ] No duplication (DRY) where the repetition is real, not speculative.
+- [ ] No dead code, commented-out blocks, or leftover debug logging.
+- [ ] No magic numbers — named constants for thresholds/limits.
+
+## 4. Tests
+
+- [ ] New behavior has tests; bug fixes include a regression test.
+- [ ] Tests assert behavior, not implementation details.
+- [ ] Error paths and edge cases are covered, not just the happy path.
+- [ ] Coverage meets the project threshold (commonly 80%) for changed lines.
+- [ ] Tests are deterministic — no sleeps, no order dependence, no shared mutable fixtures.

package/catalog/agents/code-reviewer/references/security-review.md

@@ -0,0 +1,62 @@
+# Security Review
+
+The first pass of every review. These are the highest-impact, most-missed classes. Map to OWASP Top
+10; for a deep audit escalate to the `security-auditor` agent and the `owasp-top10` skill.
+
+## Injection
+
+User input must never be interpreted as code/query syntax.
+
+```js
+// BAD — SQL injection
+db.query(`SELECT * FROM orders WHERE status = '${req.query.status}'`);
+
+// GOOD — parameterized
+db.query('SELECT * FROM orders WHERE status = $1', [req.query.status]);
+```
+
+- SQL: bind parameters; never string-concatenate. For dynamic columns (sort/filter), **whitelist**
+  the allowed set — you can't parameterize an identifier.
+- Command: avoid shelling out with user input; if unavoidable, pass an argv array, never a shell
+  string.
+- Template/XSS: escape output by default; treat any HTML built from input as suspect.
+
+## Broken authorization (IDOR)
+
+The most common real vuln in CRUD apps. Authentication ≠ authorization.
+
+```js
+// BAD — authenticated, but ownership never checked
+const doc = await db.docs.findById(req.params.id);
+
+// GOOD — verify the caller owns the resource
+const doc = await db.docs.findById(req.params.id);
+if (!doc || doc.ownerId !== req.session.userId) return res.status(404).end();
+```
+
+- Check ownership/role on **every** action that reads or mutates a specific resource.
+- Prefer 404 over 403 for resources the caller may not even know exist (avoid leaking existence).
+- Don't trust IDs, roles, or prices sent from the client — re-derive server-side.
+
+## Secrets
+
+- No hardcoded keys, tokens, passwords, or connection strings — even in tests or comments.
+- Pull from environment variables or a secret manager; validate presence at startup.
+- If a secret is found in a diff, flag CRITICAL and instruct rotation — committed secrets are
+  compromised even if later removed (git history).
+
+## Unsafe deserialization
+
+- Never deserialize untrusted data with executable formats: Python `pickle`, `yaml.load` (use
+  `safe_load`), Java native serialization, PHP `unserialize` on user input.
+- Prefer JSON with a schema validator at the boundary.
+
+## Other high-value checks
+
+- **SSRF:** outbound requests to user-supplied URLs must be allow-listed; block internal IP ranges
+  and metadata endpoints (`169.254.169.254`).
+- **Path traversal:** normalize and confine file paths to a base directory; reject `..` segments.
+- **Crypto:** constant-time comparison for tokens (`crypto.timingSafeEqual`); strong, salted hashing
+  (argon2/bcrypt/scrypt) for passwords; never MD5/SHA1 for secrets.
+- **Rate limiting:** state-changing and auth endpoints should be rate-limited (return 429).
+- **Error leakage:** no stack traces or internal details in client-facing error responses.

package/catalog/agents/code-reviewer/references/severity-rubric.md

@@ -0,0 +1,63 @@
+# Severity Rubric
+
+Every finding gets exactly one severity. Calibration matters more than volume: an inflated severity
+makes the whole review untrustworthy. When unsure between two levels, pick the lower one and explain.
+
+## CRITICAL — Block merge
+
+Exploitable vulnerability, data loss, or data corruption. The change must not merge as-is.
+
+Examples:
+- SQL/command injection reachable from user input.
+- Authentication bypass or broken authorization (IDOR) exposing other users' data.
+- Hardcoded production secret committed to the repo.
+- A migration or write path that can corrupt or delete data.
+- Unsafe deserialization of untrusted input (RCE class).
+
+**Action:** Verdict = Block. Author must fix before merge. Rotate any exposed secret immediately.
+
+## HIGH — Fix before merge
+
+A real bug or significant security/quality risk that will bite in production, but not an immediate
+exploit/data-loss.
+
+Examples:
+- Unhandled error path that crashes the process on bad input.
+- Race condition on shared state under concurrency.
+- Missing tests on a risky new code path.
+- Resource leak (unclosed connection) under load.
+- XSS via unescaped output in a low-traffic admin view.
+
+**Action:** Verdict = Request-changes. Should be fixed before merge.
+
+## MEDIUM — Should fix
+
+Maintainability concern or minor correctness issue. Won't cause an outage but adds risk or friction.
+
+Examples:
+- A 59-line function doing three jobs.
+- Duplication that will drift.
+- Deep nesting that obscures logic.
+- Missing validation on an internal, low-risk input.
+
+**Action:** Fix when reasonable; author may defer with a tracking note.
+
+## LOW — Optional
+
+Style, naming, micro-improvements. Never blocks a merge.
+
+Examples:
+- A poorly named variable.
+- A comment that's now stale.
+- A spot where a constant would read better than a literal.
+
+**Action:** Note as a nit. Verdict can still be Approve-with-nits.
+
+## Verdict mapping
+
+| Findings present | Verdict |
+|---|---|
+| Any CRITICAL | Block |
+| Any HIGH (no CRITICAL) | Request-changes |
+| Only MEDIUM/LOW | Approve-with-nits |
+| None | Approve |