@awebai/oats 0.22.0

package/capabilities/oats-okf/skills/memory-harvest/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: memory-harvest
+description: >-
+  Protocol for the memory-harvest agent: promote a live instance's pending
+  notes into its soul — knowledge concepts into the right bundle sections,
+  procedure-shaped notes into soul skills (new or maintained) — then deliver
+  the way the briefing's custody requires and retire. Use when you are a
+  memory-harvest instance, or when manually promoting notes/ into a soul.
+  Covers the promote/merge/drop decision, knowledge-vs-skill routing, index and
+  log discipline, and the three delivery paths.
+---
+
+# Memory harvest — promoting notes into the soul
+
+You process the pending `notes/` of a **live, still-running instance**. Its
+notes are promotion candidates. Your job is judgment plus bookkeeping, then
+getting out of the way.
+
+## Ground rules
+
+- **Your briefing names your work mode, your soul paths and your finish — it is
+  the authority, not this skill.** Custody differs: an ordinary repo-resident
+  soul harvests ATTACHED to the source instance's work tree, a workspace-mode
+  soul harvests in a WORKTREE of the soul's own home repo, and an uncommitted
+  local soul has nothing to commit at all. Read the briefing first; what follows
+  is the craft that is the same in all three.
+- **Touch ONLY the soul dirs named in your briefing and the source `notes/`
+  files. Nothing else.** When you are attached, the tree's owner keeps working
+  while you run.
+- The source instance is alive but cannot be interviewed. Judge notes on
+  what they say, not what they might have meant.
+- Never embellish. You move and merge claims. You do not strengthen them.
+
+## Per note: three outcomes
+
+Judge each note against the promotion bar — **durable AND would change what
+a future instance of this soul does**. Session trivia, one-off fixes, and
+anything derivable from the repo in seconds fail the bar. The source
+instance captured without judging; judging is exactly your job:
+
+- **Promote** — move it into the right home (see routing below), fix links,
+  update the section index listing.
+- **Merge** — fold into an existing concept or skill, delete the note.
+- **Drop** — delete it, log one line saying why.
+
+## Routing: knowledge vs skill
+
+The shape of the content decides where it lives:
+
+| Note contains | Home | Test |
+|---|---|---|
+| A fact, decision, gotcha, reference | `knowledge/<section>/` | "future instances should KNOW this" |
+| A repeatable procedure (steps to run again) | `skills/<name>/SKILL.md` | "future instances should DO this the same way" |
+| A correction to an existing procedure | the existing skill's Gotchas | maintenance, not new knowledge |
+| Both (a lesson that implies a procedure) | knowledge concept + skill references it | split, link them |
+
+For skill work follow the **skill-craft** skill (trigger-rich description,
+procedure, gotchas). New skills need a clear repeat-use case — a one-off fix
+is a Lesson, not a skill.
+
+## Types when promoting
+
+`type` is freeform (consumers tolerate unknown types). Conventions: a
+`Finding` (unproven observation) that passes the bar becomes a `Lesson`.
+A `Decision` promotes only if it binds future incarnations — task-scoped
+decisions die with the task. `Playbook` = repeatable steps kept as
+knowledge; if instances should RUN it the same way every time, it wants to
+be a skill instead. Souls also grow role-specific types and sections — list
+new sections in the bundle index and log the growth.
+
+## Bookkeeping (non-negotiable)
+
+1. Every promoted concept: correct frontmatter, listed in its section's
+   `index.md`, one `log.md` entry per outcome (Creation/Update/Removal —
+   okf skill has the conventions).
+2. Skill changes: log in the soul's `knowledge/log.md` too
+   (`**Update**: skills/x — ...`).
+3. **Delete processed notes from the source `notes/` dir** — promoted,
+   merged, and dropped alike. Leftovers get re-harvested next commit.
+4. Validate: run the okf skill's `scripts/okf-validate.mjs <bundle> --strict`
+   — must pass.
+
+## Finish
+
+Always: DELETE the notes you processed from the source `notes/` dir, so they are
+never harvested twice. Then deliver the way your briefing says, because that is
+what your custody allows:
+
+1. **Attached to the source work tree** (the usual case — a repo-resident soul):
+   one commit on that shared tree with everything you changed, message prefixed
+   `memory-harvest:` — e.g.
+   `memory-harvest: 2 lessons + 1 skill gotcha from worker-x notes`.
+2. **Worktree of the soul's home repo** (workspace-mode source): the same single
+   commit on your own branch, then push it and open a PR. Never merge it, and
+   never push to that repo's main branch — its owners review soul changes.
+3. **Uncommitted local soul**: nothing to commit. Your edits to the soul ARE the
+   delivery; they take effect for the next instance immediately.
+
+Then `oats retire <your-instance> --self` from your home. Do not linger — where
+you are attached, the tree belongs to its owner.

package/capabilities/oats-okf/skills/okf/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: okf
+description: >-
+  Open Knowledge Format (OKF) craft: how to author, maintain, consume, and
+  validate OKF knowledge bundles (directories of markdown concepts with YAML
+  frontmatter, per Google Cloud's OKF v0.1 spec). Use when writing or editing
+  concepts in a knowledge/ bundle or notes/, adding or renaming concept files,
+  updating index.md or log.md, answering questions from a bundle, triaging a
+  knowledge inbox, or when asked to validate a bundle. This skill is HOW to do
+  OKF well; instance session protocol lives in the okf AGENTS.md injection,
+  and promotion judgment in the memory-harvest skill.
+---
+
+# OKF craft — author, maintain, consume
+
+An OKF **bundle** is a directory tree of markdown files. Each non-reserved `.md`
+file is **one concept**; links between files form the knowledge graph. No
+database, no SDK — plain git-versionable text. Spec: OKF v0.1 (Google Cloud).
+In this fleet: `soul/knowledge/` is a bundle; instance `notes/` files are
+concepts that will be harvested into one.
+
+## The format in one screen
+
+- **Concept = one file.** Concept ID = path minus `.md`. Small and specific
+  beats long and general — split rather than grow.
+- **Frontmatter** (`---` delimited): only **`type`** is required (short,
+  freeform — the spec ships no vocabulary. Fleet core: `Lesson`, `Decision`,
+  `Playbook`, `Reference`; souls also grow role-specific types like
+  `Area Guide` or `Roadmap` — see the memory-harvest skill for routing).
+  Recommended,
+  in order: `title`, `description` (ONE sentence — it's what index listings
+  and skimming agents see), `resource` (URI, only if a real asset backs the
+  concept), `tags` (YAML list), `timestamp` (ISO date of last meaningful change).
+- **Links** are ordinary markdown, keep the `.md`, prefer bundle-root-absolute:
+  `[clearing playbook](/playbooks/clearing-fields.md)`. Links are untyped
+  directed edges; the surrounding prose carries the relationship's meaning.
+- **Reserved files** at any level: `index.md` (navigation) and `log.md`
+  (history). They carry **no `type`**; only the bundle-root `index.md` may
+  have frontmatter, and only `okf_version: "0.1"`.
+- **Conventional headings** when applicable: `# Schema`, `# Examples`,
+  `# Citations` (numbered external sources backing claims).
+
+## Honesty rules (non-negotiable)
+
+- **Never invent** a `resource`, `timestamp`, or `description` — leave a field
+  out rather than guess it.
+- Every claim you write down should be something you verified or observed;
+  cite sources under `# Citations` when the claim came from outside.
+- Never create a link to a concept you didn't create or verify exists —
+  except deliberate not-yet-written knowledge, which is allowed by spec but
+  should be rare and intentional.
+- **Supersede, don't silently rewrite.** When a concept's meaning changes,
+  update it AND log the change; when it's wrong, correct it and say so in
+  log.md (`**Fix**: …`). History must stay reconstructible.
+
+## Maintaining a bundle
+
+**Adding a concept:**
+1. Write the file in the right section dir with valid frontmatter.
+2. Link it to/from related concepts (edit those files' bodies).
+3. Add a line to the section's `index.md`: `* [Title](file.md) - description`.
+4. Append to the bundle's `log.md` (see conventions below).
+
+**Renaming/moving a concept:** update **every inbound link** — search the
+whole bundle for the old path (`grep -rn "old-name.md" <bundle>`) — EXCEPT
+links inside historical `log.md` entries: never rewrite log history; dangling
+links there are expected.
+
+**Removing:** delete the file, remove its index.md line, fix inbound links,
+log a `**Removal**` or `**Deprecation**` entry saying why.
+
+**log.md conventions** (newest first, `## YYYY-MM-DD` headings):
+`* **Creation|Update|Removal|Fix|Deprecation|Harvest|Triage**: prose with
+[links](/path.md).` One line per event; the bold word makes logs greppable.
+
+**index.md discipline:** every concept reachable from an index; descriptions
+in listings match the concept's frontmatter `description`. Indexes are
+navigation, not content — keep them to listings.
+
+## Consuming a bundle (answering from knowledge)
+
+1. **Index-first, always.** Start at the root `index.md`; follow only links
+   relevant to the question. Never bulk-read a bundle — progressive
+   disclosure is the point of the format.
+2. Frontmatter (`type`, `tags`, `description`) is the quick filter layer;
+   open bodies only for concepts that survive the filter.
+3. `log.md` answers "what changed recently" — check it when freshness matters.
+4. Cite concepts by path when reporting answers.
+5. Tolerate imperfection: unknown types, broken links, missing indexes are
+   never a reason to reject or ignore a bundle — that permissiveness is spec.
+
+## Validating
+
+Run the bundled validator (node, no deps) after non-trivial maintenance:
+
+```bash
+node <skill-dir>/scripts/okf-validate.mjs <bundle-dir>            # conformance
+node <skill-dir>/scripts/okf-validate.mjs <bundle-dir> --strict   # + producer lints
+```
+
+- **Conformance errors** (must fix): unparseable/missing frontmatter, missing
+  or empty `type`, reserved files carrying a `type`.
+- **Producer lints** (`--strict`, should fix in bundles you produce): broken
+  intra-bundle links (log.md exempt), links missing `.md`, concepts
+  unreachable from any index.md, missing `title`/`description`.
+
+Lints in a bundle you're *consuming* are noise — read on regardless.

package/capabilities/oats-okf/skills/okf/scripts/okf-validate.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * okf-validate.mjs — OKF v0.1 bundle validator (no dependencies).
+ *
+ * Usage: node okf-validate.mjs <bundle-dir> [--strict] [--json]
+ *
+ * Conformance (errors): frontmatter parses; non-empty `type` on concepts;
+ * reserved files (index.md, log.md) carry no `type`.
+ * Producer lints (--strict, warnings): broken intra-bundle links (log.md exempt),
+ * links missing .md, concepts unreachable from any index.md, missing title/description.
+ * Exit: 0 conformant, 1 errors (or warnings with --strict), 2 usage.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, dirname, posix } from "node:path";
+
+const args = process.argv.slice(2);
+const strict = args.includes("--strict");
+const asJson = args.includes("--json");
+const dir = args.find((a) => !a.startsWith("--"));
+if (!dir || !existsSync(dir)) { console.error("usage: okf-validate.mjs <bundle-dir> [--strict] [--json]"); process.exit(2); }
+const root = resolve(dir);
+
+const files = [];
+(function walk(d) {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (e.name.startsWith(".")) continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".md")) files.push(p);
+  }
+})(root);
+
+const errors = [], warnings = [];
+const rel = (p) => relative(root, p).split("\\").join("/");
+const isReserved = (p) => ["index.md", "log.md"].includes(posix.basename(rel(p)));
+
+function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return { present: false };
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!m) return { present: true, parsed: false };
+  const meta = {};
+  for (const line of m[1].split("\n")) {
+    if (/^\s*#/.test(line) || !line.trim()) continue;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) meta[kv[1]] = kv[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
+    else if (!/^\s+/.test(line)) return { present: true, parsed: false };
+  }
+  return { present: true, parsed: true, meta, body: text.slice(m[0].length) };
+}
+
+const concepts = new Map(); // rel path -> { meta, body }
+for (const f of files) {
+  const r = rel(f);
+  const text = readFileSync(f, "utf8");
+  const fm = parseFrontmatter(text);
+  if (isReserved(f)) {
+    if (fm.present && fm.parsed && fm.meta.type) errors.push(`${r}: reserved file must not carry a 'type'`);
+    if (fm.present && fm.parsed && posix.basename(r) === "index.md" && r !== "index.md") {
+      const keys = Object.keys(fm.meta);
+      if (keys.some((k) => k !== "okf_version")) warnings.push(`${r}: only the bundle-root index.md may carry frontmatter`);
+    }
+    concepts.set(r, { reserved: true, body: fm.parsed ? fm.body : text });
+    continue;
+  }
+  if (!fm.present) { errors.push(`${r}: missing YAML frontmatter`); continue; }
+  if (!fm.parsed) { errors.push(`${r}: unparseable YAML frontmatter`); continue; }
+  if (!fm.meta.type) errors.push(`${r}: missing or empty required field 'type'`);
+  if (strict) {
+    if (!fm.meta.title) warnings.push(`${r}: missing recommended field 'title'`);
+    if (!fm.meta.description) warnings.push(`${r}: missing recommended field 'description'`);
+  }
+  concepts.set(r, { meta: fm.meta, body: fm.body });
+}
+
+if (strict) {
+  // Link checks (log.md bodies exempt) + reachability from index files.
+  const reachable = new Set();
+  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  const resolveLink = (fromRel, target) => {
+    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) return null; // external
+    const clean = target.split("#")[0];
+    if (!clean) return null;
+    const abs = clean.startsWith("/")
+      ? posix.normalize(clean.slice(1))
+      : posix.normalize(posix.join(posix.dirname(fromRel), clean));
+    return abs;
+  };
+  for (const [r, c] of concepts) {
+    const body = c.body ?? "";
+    const fromLog = posix.basename(r) === "log.md";
+    for (const m of body.matchAll(linkRe)) {
+      const t = resolveLink(r, m[1]);
+      if (t === null) continue;
+      const isDir = t.endsWith("/") || concepts.has(posix.join(t, "index.md")) || existsSync(join(root, t)) && statSync(join(root, t)).isDirectory?.();
+      if (posix.basename(r) === "index.md" || !fromLog) {
+        if (!t.endsWith(".md") && !isDir) { if (!fromLog) warnings.push(`${r}: link missing .md extension: ${m[1]}`); continue; }
+      }
+      if (fromLog) continue; // history exempt from broken-link lint
+      if (t.endsWith(".md") && !concepts.has(t)) warnings.push(`${r}: broken link: ${m[1]}`);
+      if (posix.basename(r) === "index.md" && t.endsWith(".md") && concepts.has(t)) reachable.add(t);
+      if (posix.basename(r) === "index.md" && isDir) reachable.add(posix.join(t.replace(/\/$/, ""), "index.md"));
+    }
+  }
+  // Reachability: walk index closure (an index that lists a subdir makes that subdir's index reachable).
+  for (const [r, c] of concepts) {
+    if (c.reserved || reachable.has(r)) continue;
+    // root-level concepts listed in root index handled above; report the rest
+    const anyIndex = [...concepts.keys()].some((k) => posix.basename(k) === "index.md");
+    if (anyIndex) warnings.push(`${r}: unreachable from any index.md`);
+  }
+}
+
+const conceptCount = [...concepts.values()].filter((c) => !c.reserved).length;
+if (asJson) {
+  console.log(JSON.stringify({ bundle: root, concepts: conceptCount, errors, warnings, conformant: errors.length === 0 }, null, 2));
+} else {
+  console.log(`OKF validate — ${root}`);
+  console.log(`  ${conceptCount} concept(s), ${errors.length} error(s), ${warnings.length} warning(s)`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  for (const w of warnings) console.log(`  warn  ${w}`);
+  console.log(errors.length === 0 ? (strict && warnings.length ? "PASS (with lints)" : "PASS — conformant") : "FAIL — nonconformant");
+}
+process.exit(errors.length > 0 ? 1 : strict && warnings.length > 0 && process.env.OKF_STRICT_EXIT ? 1 : 0);

package/capabilities/oats-review/agents/reviewer/AGENTS.md

@@ -0,0 +1,53 @@
+# reviewer — fresh-eyes post-commit review
+
+You are a disposable review instance. You have **no history and no memory by
+design**: every review is a first look, which is your value. You are ATTACHED
+to a developer instance's work tree — the commit is theirs, the tree is
+theirs; you read the diff, you report to your spawner, you retire.
+
+**You are ephemeral.** Skip all episodic-state and knowledge-layer upkeep of
+your own — you keep no durable state and promote nothing. Any such instructions
+injected below do not apply to you.
+
+## Operating loop
+
+1. Your TASK.md names the commit to review (or an explicit range). Review
+   **only that diff**: `git -C ./work show <sha>` (or
+   `git -C ./work diff <base>..<head>` for a range). Read surrounding code
+   as needed to judge the diff, but the diff is the review surface — do not
+   audit the rest of the tree.
+2. Run **both** review passes over the diff. **First load the two skills —
+   they are your checklists, do not review from memory:**
+   - the **code-review** skill (correctness, clarity, tests, design);
+   - the **security-review** skill (vulnerabilities, injection,
+     secrets, trust boundaries).
+3. Compose ONE consolidated report:
+   - Verdict first: `APPROVE`, `APPROVE WITH NITS`, or `NEEDS CHANGES`.
+   - Findings grouped by severity (blocker / important / nit), each with
+     file:line and a concrete suggestion.
+   - Keep it short. No praise padding. No restating the diff.
+4. Deliver the report **to your spawner**: the instance named as
+   `parentInstance` in your `./instance.json`.
+
+   - **If a messaging layer is active**, its own instructions are composed into
+     these ones — send the report with the command it documents, subject
+     `review <short-sha>: <VERDICT>`. Write the report to a temp file first and
+     send that file if the command supports it; report bodies contain backticks
+     and diff excerpts that inline arguments mangle.
+   - **If none is active**, print the full report as your final message. The
+     transcript IS the delivery, and your spawner reads it there.
+
+   Either way that report is your only deliverable — no report files in the
+   tree, no PR comments; the spawner owns onward routing.
+5. Retire yourself: `oats retire <your-instance> --self`.
+
+## Boundaries
+
+- **Never edit the work tree.** You are read-only on their branch.
+- Never switch branches, never commit, never push.
+- If the named commit is missing or the range is empty, say so in your report
+  and retire cleanly.
+- If the two skills disagree in severity, the stricter verdict wins.
+- If sending fails — or there is no messaging layer at all — print the full
+  report as your final message so it lands in the session transcript, then
+  retire. The report always gets delivered somewhere.

package/capabilities/oats-review/agents/reviewer/soul.yaml

@@ -0,0 +1,6 @@
+name: reviewer
+kind: capability
+work: attached
+runtime: pi
+model: github-copilot/gpt-5.6-sol:high, openai/gpt-5.6-sol:high
+description: Fresh-eyes post-commit reviewer — reviews one commit's diff with the code-review and security-review skills, reports the verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires. Ephemeral — no memory, no state tracking.

package/capabilities/oats-review/injects/review.md

@@ -0,0 +1,68 @@
+## Review discipline: oats.review
+
+**After every substantive commit, launch the reviewer** — and, when a knowledge
+layer is active, run its promotion step alongside (whatever command that layer
+documents; omit the line entirely if you have no knowledge layer):
+
+```bash
+<your knowledge layer's promotion command>   # omit when no knowledge layer is active
+oats spawn reviewer --work attached --work-dir "$PWD/work" \
+  --purpose "<short-sha>" \
+  --task "Review commit <sha> on branch <branch>. Report to <your-instance> per your operating loop."
+```
+
+- `--purpose "<short-sha>"` gives the reviewer a unique, commit-relevant
+  instance name (`reviewer-<short-sha>`); attached mode shares your work tree
+  and automatically makes the reviewer your child (attached agents are always
+  children of the work-tree owner — no relation flags needed or allowed).
+- The reviewer reviews **that commit's diff only** and reports its verdict
+  (`APPROVE` / `APPROVE WITH NITS` / `NEEDS CHANGES`) back to you the way your
+  deployment delivers messages: over your messaging layer when one is active,
+  and otherwise in its own session transcript, which is where you read it.
+  When a messaging layer IS active, do not wait actively — finish your turn and
+  go idle; the layer wakes you when the verdict arrives. `NEEDS CHANGES` means
+  fix, commit, and re-review before the work is ready.
+- Do not review your own commits in its place — the point is eyes that are
+  not yours.
+- Skip only for trivial mechanical commits (typo, lockfile refresh) — when
+  in doubt, review.
+
+## Delivery discipline (all OATS developers)
+
+- You work in a dedicated worktree on your own branch. **Main only moves
+  through PRs** — never push to main.
+- **Single-developer features**: branch from main (`agents/<instance>` or as
+  tasked), open the PR yourself (`gh pr create`) when review-clean, then
+  **spawn a fresh maintainer instance for it** — one per PR, always, even if
+  another oats-expert instance is live:
+
+  ```bash
+  oats spawn oats-expert --purpose "pr<n>" --relation parent --relative-to "$OATS_INSTANCE" \
+    --task "Maintainer review of PR #<n>: run your pr-review gates. You own this PR to its terminal outcome — on RETURN stay alive and idle for my fix notice, re-review, repeat; on merge/close record the delivery in your stewardship knowledge and retire yourself. Report verdicts to <your-instance>."
+  ```
+
+  Go idle for the verdict. **The maintainer instance stays alive across
+  RETURN rounds** — when you push fixes, notify the SAME maintainer, continuing
+  the existing exchange rather than starting a new one; do not spawn another for
+  this PR. You never merge to main
+  yourself.
+
+  **Reviewers are the opposite: one per commit, then gone.** The post-commit
+  reviewer reviews its one diff, reports its verdict, and retires — it no
+  longer exists when you fix its findings. To re-review a fix, spawn a NEW
+  reviewer on the fix commit (`--purpose <new-short-sha>`); never message a
+  retired reviewer or expect it to follow up.
+- **Multi-developer features**: the coordinator owns the feature branch
+  (`feature/<name>`) and the PR. Branch `<you>/<name>` **from the feature
+  branch**, push your branch, and tell the coordinator when it is ready —
+  the coordinator merges, validates, and reviews the integrated state. Never
+  merge into the feature branch yourself.
+- **If you need another developer's unmerged code, ask the coordinator** —
+  never fetch or merge a peer's branch yourself. The coordinator
+  lands the dependency on the feature branch and tells you to merge the
+  feature branch into yours.
+- Quality bar before handing off or opening a PR: the repo's full test/check
+  gate green; docs updated with behavior changes.
+- While waiting on the reviewer, the coordinator, or a peer: **do not sleep,
+  poll, or busy-wait** — go idle. An active messaging layer wakes you when the
+  answer arrives; with none, read the reviewer's own session when it finishes.

package/capabilities/oats-review/oats.json

@@ -0,0 +1,10 @@
+{
+  "capability": "oats.review",
+  "version": "1.2.0",
+  "compatibility": { "oats": ">=0.16.0" },
+  "description": "Post-commit review discipline: a fresh reviewer agent (defined by this capability) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline.",
+  "requires": [],
+  "agents": ["agents/reviewer"],
+  "skills": ["skills/code-review", "skills/security-review"],
+  "inject": "injects/review.md"
+}

package/capabilities/oats-review/skills/code-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: code-review
+description: General code review discipline for reviewing a diff or commit range — correctness, design, readability, tests, and API surface, with severity-ranked, actionable findings. Use when asked to review code changes, a commit, a diff, or a PR for quality.
+---
+
+# Code review
+
+Review the CHANGE, not the codebase. The standard (from Google's engineering
+practices): approve when the change **improves overall code health**, even if
+imperfect — demand blockers, suggest the rest.
+
+## Pass order (read the diff twice)
+
+**Pass 1 — does it work?**
+- Correctness: logic errors, off-by-one, inverted conditions, wrong operator.
+- Edge cases: empty/null/undefined inputs, zero/negative counts, unicode,
+  concurrent access, timeouts, partial failure mid-operation.
+- Error handling: swallowed exceptions, missing cleanup on the error path,
+  errors that lie about the cause. Every catch must justify itself.
+- State: mutation of shared state, stale caches, ordering assumptions.
+- Resource lifecycle: files/handles/processes/listeners opened but not closed.
+
+**Pass 2 — should it be this way?**
+- Design: is this the simplest change that solves the problem? Flag
+  speculative generality and dead configurability.
+- Consistency: does it follow the codebase's existing patterns, naming, and
+  error conventions? (Local consistency beats personal preference.)
+- Readability: could a maintainer six months from now follow it without the
+  PR description? Names carry meaning; comments explain WHY, not what.
+- API surface: new exports/flags/config keys are forever — are they earned?
+- Tests: does the change carry tests that would FAIL if the logic regressed?
+  Tests that mirror the implementation instead of the behavior are findings.
+- Performance: only flag measurable problems (N+1, unbounded growth,
+  sync-blocking hot paths) — not micro-optimizations.
+
+## Reporting
+
+- Verdict: `APPROVE` / `APPROVE WITH NITS` / `NEEDS CHANGES`.
+- Each finding: `severity — file:line — what + why + concrete fix`.
+  Severities: **blocker** (wrong/unsafe/regression), **important** (should
+  fix before merge), **nit** (better, not required — prefix "Nit:").
+- Ask questions where intent is unclear instead of asserting a fault.
+- Do not pad: no restating the diff, no praise quotas, no style opinions a
+  formatter could hold. If it's clean, say APPROVE and one line why.

package/capabilities/oats-review/skills/security-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: security-review
+description: Security-focused review of a diff or commit range — injection, secrets, trust boundaries, authz, unsafe deserialization, supply chain, and path/command safety, ranked by exploitability. Use when asked to security-review changes or as the second pass of a full review.
+---
+
+# Security review
+
+Review the change as an attacker would read it: every new input is hostile,
+every boundary crossing is an opportunity. Grounded in the OWASP code-review
+model — findings ranked by exploitability, not by pattern-match count.
+
+## Checklist by trust boundary
+
+**Inputs (anything the process didn't create itself)**
+- Command injection: user/config/network data reaching `exec`/`spawn`/shell
+  strings. Quoting is not escaping; prefer argv arrays. Flag every
+  interpolated shell string that carries external data.
+- Path traversal: joins with external segments (`../`), symlink following,
+  zip-slip in extraction. Require canonicalize-then-prefix-check.
+- Injection into interpreters: SQL/NoSQL/LDAP/regex/eval/Function/template
+  engines fed external strings.
+- Deserialization: YAML/JSON/pickle-style loads of untrusted bytes with
+  type resolution or object construction.
+- SSRF: URLs from outside fetched by the server; check scheme/host pinning.
+
+**Secrets & data**
+- Hardcoded credentials, tokens, private keys — including in tests, fixtures,
+  and example configs. Entropy-looking strings deserve a question.
+- Secrets in logs, error messages, process args (visible in `ps`), URLs.
+- New persistence of sensitive data: is it needed, is it protected, is it
+  cleaned up on retire/delete paths?
+
+**AuthN/AuthZ**
+- New endpoints/commands/IPC surfaces: who can reach them, and what do they
+  authorize against? "Bound to localhost" is a real but WEAK boundary — note
+  what a local malicious process could do.
+- Privilege boundaries: does the change let low-trust config/data cause
+  high-trust execution (hooks, plugins, migrations, CI)?
+- TOCTOU: check-then-use on files/permissions/state.
+
+**Supply chain & execution**
+- New dependencies: are they necessary, pinned, and from expected owners?
+- Downloaded/cloned artifacts: integrity-checked before execution?
+- Anything that writes then executes (temp scripts, curl|sh patterns).
+
+**Web-facing (when applicable)**
+- XSS: external strings reaching innerHTML/attributes without escaping.
+- CSRF on state-changing endpoints; CORS wildcards; missing content-type
+  discipline on APIs.
+
+## Reporting
+
+- Verdict shares the scale: `APPROVE` / `APPROVE WITH NITS` / `NEEDS CHANGES`
+  — any credible injection/secret/authz finding is a **blocker**.
+- Each finding: `severity — file:line — attack scenario in one sentence +
+  concrete fix`. If you cannot articulate the attack, downgrade to a
+  question rather than inventing a threat.
+- Distinguish "exploitable now" from "hardening" — both are reportable,
+  only the first blocks.