---
name: evaluate-library
description: Walk the 9-filter + 3-prompt library evaluation protocol for a named package, write the decision trace to docs/library-decisions/, and return pass/fail. Use when adding a runtime dependency to a feature or core package, or when the library-policy-nudge hook fires.
---

<invocation>

```
/evaluate-library <package-name> --tier <feature|core|app> --target <package-path>
```

All three arguments are required. The `library-policy-nudge` hook emits this exact invocation. For `app`-tier packages, evaluation still runs but a trace is optional (author's call per ADR-022 §1).

</invocation>

<runbook>

## Overview

Walk nine hard auto-reject filters in **collect-cheap-skip-expensive** order, then answer three discussion prompts. Write the trace unconditionally at the end — including for rejections. A rejection trace is a permanent record that prevents future agents from re-litigating the same decision.

## Phase 1 — Cheap filters (always run to completion, even if one fails)

Run all four cheap filters regardless of their outcomes. Record each result before moving to Phase 2.

### Filter 1: license

Command: `node -e "const p = JSON.parse(require('fs').readFileSync('./node_modules/<pkg>/package.json','utf8')); console.log(p.license)"`

Allowlist: `MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MPL-2.0`.

Result values: the SPDX identifier (e.g. `MIT`) if allowed, or `<SPDX-id> (rejected)` if outside the allowlist. Anything outside the allowlist is an automatic reject but does not stop Phase 1.

### Filter 2: types

Check whether TypeScript types ship with the package or via `@types/<pkg>`:

```
ls node_modules/<pkg>/index.d.ts 2>/dev/null && echo native || npm info @types/<pkg> version 2>/dev/null | head -1
```

Result values: `native` (ships its own `.d.ts`), `@types/<pkg>` (community types available), or `none` (auto-reject — un-typed library shifts maintenance cost to the feature).

### Filter 3: shadow-check

Check whether this library duplicates a must-have already locked in the workspace. Locked must-haves: `zod` (validation), `inversify` (DI, ADR-002), `payload` (CMS), `@trpc/server` (API layer), `superjson` (serialisation), `reflect-metadata` (DI metadata).

Command: `cat package.json | grep -E '"(zod|inversify|payload|@trpc/server|superjson|reflect-metadata)"'` — run from the workspace root.

Result values: `pass` (no shadow), `fail` (exact duplicate of a locked dep), `"shadows <x>"` (functional parallel that would create two libraries doing the same job — auto-reject). A replacement must be a separate ADR with consequences analysis, not a parallel adoption.

### Filter 4: boundary-fit

Confirm the dependency does not violate ESLint boundary-tag rules for the target tier (ADR-006, ADR-010, ADR-017).

Key rules:

- Feature packages cannot import `@sentry/*` or `@opentelemetry/sdk-*` directly — those are reserved for core (ADR-017 §4).
- No package may import across feature boundaries without going through the event bus or tRPC.
- Optional core packages can only be imported by apps and `core-composition`-tagged packages.

Check by reviewing what the proposed library's transitive imports would bring in and whether any violate the boundary ruleset.

Result values: `pass` or `fail`.

---

After Phase 1: tally results. If **any cheap filter failed**, the overall decision is `rejected`. Proceed to Phase 2 anyway — all expensive filters still run if the Phase 1 decision is already rejected (they inform the full record). If all cheap filters passed, proceed to Phase 2 to determine the final decision.

## Phase 2 — Expensive filters (short-circuit after first reject)

Run in order. On the first failure, set remaining filter results to `skip` and skip to the [Trace write step](#trace-write-step).

### Filter 5: maintenance

Check last release date and recent PR/issue activity:

```
npm info <pkg> time.modified
npm info <pkg> time | tail -5
```

Result values:

- `active` — last release < 18 months **and** PR/issue activity < 12 months
- `dormant` — stable, not actively developed (acceptable for finished libraries like `reflect-metadata`)
- `abandoned` — last release ≥ 18 months **or** no activity in ≥ 12 months → auto-reject; short-circuit remaining expensive filters

On `abandoned` → set `cve-scan`, `eu-residency`, `named-consumer`, `socketRisk` to `skip` → write trace.

### Filter 6: cve-scan

```
pnpm audit --audit-level=moderate 2>&1 | head -40
```

Result values: `clean` (no advisories), an advisory ID like `GHSA-xxxx-xxxx-xxxx` (accepted risk — document in `accepted-cves` frontmatter), or `fail` (open advisory not accepted → auto-reject; short-circuit remaining expensive filters).

On `fail` → set `eu-residency`, `named-consumer`, `socketRisk` to `skip` → write trace.

### Filter 7: eu-residency

Applies only if the library transmits user data, telemetry, business state, or secrets to a vendor-controlled endpoint by default. Examples: analytics SDKs, error-tracking clients, AI APIs, log aggregation services.

Exemptions (result: `n/a`): pure in-process libraries (no network calls), self-hostable software where the operator controls the endpoint, and build-time-only tools.

For non-exempt libraries: verify the vendor offers an EU data region AND that the integration in `target` is configured to use it.

Result values: `ok` (vendor offers EU region, integration configured), `n/a` (no data transmission), `self-hostable` (operator-controlled endpoint), `fail` → auto-reject; short-circuit `named-consumer`.

On `fail` → set `named-consumer`, `socketRisk` to `skip` → write trace.

### Filter 8: named-consumer

Answer: **Who calls this code path today, or who is blocked waiting for it?**

A named consumer is a concrete call site that exists now or a feature blocked on this capability today. "We might want this later", "external clients could use this", and "it would be nice to have" are not named consumers.

If the only possible callers are hypothetical or future → `fail` → set `socketRisk` to `skip` → auto-reject.

Result value: `pass` or `fail`.

### Filter 9: supply-chain behavior (Socket)

**Expensive — network call. Run last in Phase 2. Short-circuit: if any earlier Phase 2 filter already rejected the library, set `socketRisk` to `skip` and proceed to the [Trace write step](#trace-write-step).**

Verify the package's supply-chain health via `socket-cli`:

```
npx socket-cli@latest scan . --json 2>&1
```

This scans the current directory's lockfile for packages installed from the target under evaluation. For a targeted single-package check before installing:

```
npx socket-cli@latest info <pkg>@<version> --json 2>&1
```

The JSON output contains an array of findings, each with a `severity` field. Cross-reference with the repo-root `.socket.json` `issueRules` to determine the classification:

| Finding severity                    | `.socket.json` rule | `socketRisk` value  |
| ----------------------------------- | ------------------- | ------------------- |
| No findings, or only `medium`/`low` | `ignore`            | `clean`             |
| `high`-severity finding present     | `warn`              | `flagged`           |
| `critical`-severity finding present | `error`             | `<finding-summary>` |

Where `<finding-summary>` is a concise label for the critical finding (e.g. `"new-author-on-publish"`, `"install-scripts-added"`, `"exfiltrates-env"`).

Set `filter-results.socketRisk` in the trace frontmatter to one of these three values.

Result values:

- `clean` — no meaningful supply-chain signals; proceed to Phase 3 prompts.
- `flagged` — `high`-severity finding; document the specific signal in the trace body and decide whether to accept with justification. Not an auto-reject.
- `<finding-summary>` — `critical`-severity finding; auto-reject. This is the last filter — no further filters to skip.

---

## Skip sentinel

When a filter is short-circuited (not evaluated), write `skip` for its frontmatter value. The Zod schema validates approved traces end-to-end; rejected/partial traces may carry `skip` in fields that would normally require an enum value. The pre-commit check only validates that approved traces exist for new deps — partial traces are informational records.

## Three discussion prompts

Answer all three in the trace, regardless of filter outcome. These are not auto-reject filters; any answer is acceptable with justification.

### Prompt: replaces

What existing library or approach does this replace? New-and-old running in parallel is a smell — name the thing being retired and the retirement plan, or explain why parallel adoption is intentional and time-bounded.

### Prompt: migration-cost-out

What does ripping this back out look like 18 months from now? Rate: **mechanical** (swap one package, update call sites), **hard** (scattered integration points, data-format dependencies), or **impossible** (vendor lock-in, protocol coupling). Higher cost raises the bar for adoption.

### Prompt: alternatives-considered

Name at least two alternatives evaluated before choosing this library. For `core`-tier adoptions, this section is also duplicated into the companion ADR. If no alternatives exist, explain why (e.g., the library is the de-facto standard with no viable substitutes).

---

## Sub-processor classification

Answer these two questions before writing the trace. The answers become
top-level frontmatter fields required by ADR-022 §9.

### Question: is-sub-processor

**Does the vendor receive personal data on the operator's behalf?**

A library is a sub-processor when it transmits personal data (user identifiers,
email addresses, behavioural events, request bodies, etc.) to a vendor-controlled
endpoint — analytics SDKs, error-tracking clients, AI APIs, log aggregation
services. Network calls alone do not make a library a sub-processor; only calls
that carry personal data do.

Pure in-process libraries (no network calls), self-hostable software where the
operator controls the endpoint, and build-time-only tools are **not** sub-processors.

Set `is-sub-processor: true | false`.

### Question: processes-pii

**Does the library process personal data in-process, even without transmitting
it to a vendor?**

A library processes PII if it reads, validates, serialises, stores, or
transforms data fields that may contain personal information (names, emails,
IDs, content authored by users, authentication credentials). A self-hosted
database or CMS is a prime example: no data leaves to a vendor, yet the
library clearly handles PII.

Pure utility libraries (DI containers, type validators, serialisers operating
on already-typed objects without inspecting field semantics, test runners)
typically answer `false`.

Set `processes-pii: true | false`.

### Conditional block: when is-sub-processor is true

When `is-sub-processor: true`, five additional fields are **required** in the
trace frontmatter. Gather them before writing the trace:

```
data-sent: "<what personal data the library transmits to the vendor>"
region: "<vendor data region, e.g. eu-west-1 or eu>"
dpa-signed: true | false     # has the operator signed a DPA with this vendor?
sccs-required: true | false  # does the vendor require SCCs (non-EEA transfer)?
contact: "<vendor DPO or privacy contact email/URL>"
```

If the vendor does not yet have a signed DPA or if you cannot determine the
region, record `dpa-signed: false` / region as best-known and add a prose note
under `## Sub-processor` in the trace body explaining the gap.

---

## Trace write step

Write the trace **unconditionally** at evaluation end — even for rejections, even for partial traces.

**Path:** `docs/library-decisions/<YYYY-MM-DD>-<package-name>.md`

Use today's date. Use `docs/library-decisions/_template.md` as the structural guide.

Frontmatter rules:

- `decision: approved` only if all eight filters passed. Otherwise `decision: rejected`.
- `adr: null` for feature-tier. For core-tier approvals, coordinate the ADR slug before writing (`adr: adr-NNN`).
- `verification-commands` — include the literal commands run for each filter, one per line.
- `accepted-cves: []` (empty unless you accepted a specific advisory).
- `is-sub-processor` and `processes-pii` are **always required** (see Sub-processor classification above).
- When `is-sub-processor: true`, include `data-sent`, `region`, `dpa-signed`, `sccs-required`, and `contact`.
- For skipped expensive filters, write `skip` for the frontmatter value and omit the prose section body or note "Not evaluated — skipped due to earlier rejection."

Frontmatter template:

```yaml
---
package: <name>
version: "<semver range>"
tier: app | feature | core
decision: approved | rejected
date: <YYYY-MM-DD>
deciders: [<author>, ...]
adr: adr-NNN | null
lastRevalidated: null
is-sub-processor: false
processes-pii: false
# include the block below only when is-sub-processor: true
# data-sent: "<description>"
# region: "<eu | eu-west-1 | ...>"
# dpa-signed: false
# sccs-required: false
# contact: "<url or email>"
filter-results:
  license: <SPDX id>
  types: native | "@types/<x>" | none
  maintenance: active | dormant | abandoned
  boundary-fit: pass | fail
  shadow-check: pass | fail | "shadows <x>"
  eu-residency: ok | n/a | self-hostable | fail
  cve-scan: clean | "<advisory-id>" | fail
  named-consumer: pass | fail
  socketRisk: clean | flagged | <arbitrary-string>
verification-commands:
  - <literal command that produced each filter result>
accepted-cves: []
---
```

After writing the trace:

- For approved traces: confirm the trace is staged in the same commit as the `package.json` change. The pre-commit hook validates this.
- For rejected traces: stage the trace file alone. Do not run `pnpm add <pkg>`.

</runbook>

<output-format>

After completing the evaluation, emit a one-paragraph summary:

```
/evaluate-library result: <approved|rejected> — <package>@<version> (<tier>)
Rejection filters (if any): <filter names>
Trace written to: docs/library-decisions/<date>-<package>.md
```

</output-format>