# Plugin review (maintainer guide)

How to review a registry PR safely + fast. CI does the mechanical checks; you
make the security + fit judgment calls. The registry pinned-SHA is the single
chokepoint — a community plugin can never reach a user without a merged entry
here, so review is the real control.

## Two tiers

- **Listed** — one `plugins-registry/<id>.json` file; the code stays in the
  author's `career-ops-plugin-<name>` repo; users `add` it. The default, low
  burden.
- **Bundled** — promoted into `plugins/` (shipped, auto-updated). Reserve for
  broadly-useful, low/zero-key, well-tested plugins (how `apify`/`gmail`/`notion`
  were absorbed). Adds a maintenance commitment + a `config/plugins.example.yml`
  block + an `.env.example` entry.

## What CI already checked (don't re-do by hand)

`plugin-registry-validate` validates the entry shape + uniqueness, clones each
entry at its pinned SHA, and runs the min-file / manifest / static-audit checks
in a no-secret, read-only sandbox (no plugin code is executed). If it's red,
stop.

## Your judgment calls (the checklist)

- **Naming + identity:** repo is `career-ops-plugin-<name>`, `id` == name minus
  prefix, `sha` pinned to the commit you actually read.
- **Read the diff** (for an update, the old→new diff): does it do only what it
  says? Watch for time-bombs, env-gated branches, obfuscation.
- **Egress:** `allowedHosts` are real public hosts; no IP literals / metadata /
  `*.internal`; localhost only with a stated reason.
- **Capability surface:** hooks ⊆ the five; no apply/submit; no core-owned
  secrets in `requiredEnv`. For an **update**, any growth in hooks / env / hosts
  is a fresh consent surface — review as a new listing.
- **Data direction:** reads PUBLIC data or the user's OWN account only. No
  centralized infrastructure, no auto-submit, no blind-apply.
- **Wording (public-forever):** description / README / skill carry no commercial
  / hosted-service / monetization language. career-ops is free and local-first;
  "approved" means "we reviewed this commit", nothing more.
- **Skill (if any):** domain-scoped — it teaches how to drive the plugin, and
  does NOT instruct the agent to edit core files, change scoring, reveal secrets,
  or act outside the plugin's hooks.
- **License:** MIT-compatible.

## Auto-merge (only when it's truly safe)

Most updates are human-reviewed. An update may auto-merge ONLY when ALL hold: a
known author (2FA + a verified commit signature on the pinned SHA), the diff is
**provably non-logic** (metadata / version / strings / comments / whitespace
only — no change to control flow or executable statements), **zero** new
capability (hooks/env/hosts/deps), every deterministic gate green, and the
agentic reviewer raised no flag. Auto-merge lands the row **staged**; the user's
shipped pin advances only after the canary window. First listings and any
capability or logic change are reviewed by a human regardless of author trust.
The agentic reviewer can only **raise** risk (escalate to a human) — never
approve.

## ToS-grey / authenticated integrations

Anything that scrapes a platform behind a login or whose terms forbid automated
access (authenticated LinkedIn, session-gated boards) is **not** bundled and
**not** registry-listed. It can still be a `career-ops-plugin-<name>` repo users
install explicitly into `plugins.local/` with the full "you're trusting this
author" prompt — the project doesn't host that liability in-tree.

## Bundled plugins are reference seeds (no feature PRs on `plugins/`)

A bundled plugin (`plugins/apify`, `plugins/gmail`, `plugins/notion`) is a
**reference seed**: a reviewed, minimal, stable example. We do **not** accept
feature PRs against it — close-redirect them to "publish `career-ops-plugin-<id>`
and we'll register it as the maintained successor." Bundled plugins only take
PRs for **security or release-compat fixes** (keeping the seed working across
core releases).

**Reviewing a `supersedesBundled: true` registry entry.** Such an entry says
"when installed at this pin, my plugin should take precedence over the bundled
plugin of the same id." Review it with that weight:

- The entry's `id` MUST match an existing bundled plugin in `plugins/` (a
  successor for a non-existent seed is meaningless — reject).
- It is the **same trust bar as any registry entry** (naming, manifest, egress,
  static audit, pinned sha) — plus the awareness that approving it lets users
  *replace* a reviewed bundled integration. Read the diff against the seed.
- Precedence is enforced engine-side **only** for a user who installs it at the
  exact pinned sha; the bundled seed remains the always-present fallback, so an
  abandoned successor degrades gracefully (the seed simply stays in charge).
- Original-author successors (the contributor whose PR seeded the bundled
  plugin) are the natural, encouraged path — hand them the migration warmly.