Dependency Adoption Receipt

# Dependency Adoption Receipt

Use this before adding a third-party library, package, container, action, script, font, model, SDK, or hosted dependency—especially when an AI assistant suggested it.

The receipt does not prove a dependency is safe. It preserves the evidence and decision that made adoption reasonable, identifies the permissions and maintenance burden being accepted, and defines how the team can remove or replace it later.

## Quick Start

1. Describe the job without naming a package.
2. Verify the exact dependency identity and official source.
3. compare standard-library, existing-dependency, and small local alternatives.
4. inspect provenance, maintenance, licenses, vulnerabilities, and transitive surface.
5. name runtime permissions, data access, and external communication.
6. run proportionate verification in an isolated branch or environment.
7. record owner, review date, upgrade policy, and removal path.

Use `unknown` instead of guessing. An unknown can be accepted, investigated, contained, or used to reject adoption.

---

## 1. Receipt Header

```md
Dependency:
Ecosystem / registry:
Exact version or digest:
Dependency type: [runtime / development / build / CI / hosted / model / asset]
Requested by:
Decision owner:
Security reviewer:
Repository / service:
Proposed change:
Decision deadline:
Review date:
Receipt version:
```

## 2. Need Before Package

```md
User or system job:
Capability required:
Why the capability is needed now:
Expected call frequency or usage:
Failure consequence:
Performance or size budget:
Support window:
Non-goals:
```

### Avoid Premature Adoption

- [ ] The requirement is described without a vendor or package name.
- [ ] Existing platform capability was checked.
- [ ] Existing project dependencies were checked.
- [ ] A small local implementation was considered.
- [ ] The team is not adding a general framework for one narrow function.
- [ ] The requirement is not only a workaround for a temporary problem.

## 3. Suggestion Provenance

Record how the candidate entered the conversation.

```md
Suggested by: [human / AI assistant / vendor docs / existing project / audit]
Assistant or source:
Original suggestion or link:
Context the suggester had:
Context the suggester did not have:
Alternative candidates suggested:
Human who verified the package exists:
```

An AI suggestion is discovery, not evidence of identity, suitability, maintenance, or security.

## 4. Exact Identity

Do not approve a dependency from a display name alone.

```md
Canonical package name:
Registry URL:
Official source repository:
Publisher / organization:
Maintainer identities checked at:
Version:
Release date:
Immutable digest or checksum:
Signature or provenance location:
Package homepage:
Documentation version:
License expression:
```

### Identity Checks

- [ ] Registry, repository, and documentation link to one another.
- [ ] Package spelling, scope, and publisher are exact.
- [ ] The selected release exists and is not yanked or deprecated.
- [ ] Version or digest is pinned according to project policy.
- [ ] Lockfile change matches the intended package.
- [ ] Install scripts and generated files were inspected.
- [ ] Typosquatting or namespace-confusion risk was considered.
- [ ] Provenance or signature was verified when available.

## 5. Alternatives Record

| Option | Meets job | New trust surface | Maintenance cost | Exit cost | Decision |
| --- | --- | --- | --- | --- | --- |
| Platform / standard library |  |  |  |  |  |
| Existing project dependency |  |  |  |  |  |
| Small local implementation |  |  |  |  |  |
| Candidate dependency |  |  |  |  |  |
| Other candidate |  |  |  |  |  |

```md
Chosen option:
Why it wins for this job:
Tradeoff accepted:
What would change the decision:
```

## 6. Maintenance And Governance

Capture signals, not popularity theater.

```md
Latest stable release:
Release cadence:
Last meaningful maintenance activity:
Supported runtime versions:
Security policy:
Vulnerability disclosure path:
Deprecation policy:
Upgrade / migration guide:
Number of active maintainers observed:
Bus-factor concern:
Issue response pattern:
Funding or organizational backing:
Known ownership changes:
```

### Maintenance Interpretation

```md
Healthy signals:
-

Concerning signals:
-

Missing evidence:
-

Risk accepted because:
```

Stars, weekly downloads, and age can provide context, but none prove that a dependency is maintained safely or fits the product.

## 7. Supply-Chain Surface

```md
Direct dependencies added:
Transitive dependencies added:
Native binaries:
Downloaded artifacts:
Post-install or lifecycle scripts:
Code generation:
Network access during install:
Build-time secrets available:
Runtime dynamic loading:
Plugin or extension system:
SBOM location:
Provenance level or format:
```

### Transitive Review

- [ ] Dependency tree was captured before approval.
- [ ] Unexpected scopes, publishers, binaries, and scripts were reviewed.
- [ ] Duplicate large libraries or runtime versions were noted.
- [ ] Critical transitive components have an owner or monitoring path.
- [ ] SBOM output can be regenerated in CI or release flow.
- [ ] Provenance is verified rather than merely linked.

## 8. Permission And Data Map

| Capability | Needed? | Scope | Evidence | Containment |
| --- | --- | --- | --- | --- |
| Filesystem read |  |  |  |  |
| Filesystem write |  |  |  |  |
| Network access |  |  |  |  |
| Environment variables |  |  |  |  |
| Build secrets |  |  |  |  |
| User or customer data |  |  |  |  |
| Credentials / tokens |  |  |  |  |
| Database access |  |  |  |  |
| Child processes |  |  |  |  |
| Production side effects |  |  |  |  |

```md
Data sent off-device or off-network:
Retention and deletion terms:
Subprocessors or external services:
Telemetry enabled by default:
Telemetry opt-out:
Least-privilege configuration:
```

## 9. Security And Compliance Review

```md
Vulnerability sources checked:
Advisories found:
Exploitability in this use:
Patch or mitigation:
Secret-scanning result:
Static-analysis result:
Malware / reputation result:
License compatibility:
Attribution requirement:
Export, privacy, or sector constraint:
Exception owner and expiry:
```

### Stop Conditions

- [ ] Package identity cannot be established.
- [ ] The suggested package does not exist or appears newly registered around a common hallucination.
- [ ] A required permission exceeds the product need.
- [ ] A known vulnerability is exploitable in the intended path without mitigation.
- [ ] License terms conflict with distribution or business use.
- [ ] Install or build behavior cannot be inspected or contained.
- [ ] The dependency silently sends sensitive data to an external service.
- [ ] No owner accepts upgrades, incidents, and eventual removal.

Any checked stop condition requires rejection or an explicit, time-bounded exception.

## 10. Integration Boundary

Keep the dependency replaceable.

```md
Imported by:
Wrapped behind:
Public types exposed:
Provider-specific data stored:
Configuration location:
Feature flag:
Fallback path:
Failure handling:
Timeout and retry policy:
Observability:
Test seam:
```

### Boundary Review

- [ ] Calls are concentrated behind a small adapter where practical.
- [ ] Product-domain types do not unnecessarily inherit vendor types.
- [ ] Timeouts and retries match side-effect risk.
- [ ] Failure preserves user work or a manual path.
- [ ] The dependency can be disabled without a large product rewrite.
- [ ] Sensitive configuration stays outside client bundles and logs.

## 11. Verification Plan

Run checks that challenge the adoption decision, not only the happy-path API.

```md
Isolated test branch / environment:
Install command:
Lockfile reviewed by:
Unit or contract tests:
Adversarial or malformed inputs:
Failure and timeout test:
Permission test:
Bundle / binary size before and after:
Cold-start or runtime impact:
Accessibility impact:
Cross-platform matrix:
Uninstall / rollback test:
Evidence links:
```

### Verification Receipt

| Check | Expected | Actual | Evidence | Result |
| --- | --- | --- | --- | --- |
| Identity |  |  |  | Pass / fail |
| Install |  |  |  | Pass / fail |
| Functional behavior |  |  |  | Pass / fail |
| Failure behavior |  |  |  | Pass / fail |
| Permissions |  |  |  | Pass / fail |
| Security scan |  |  |  | Pass / fail |
| Performance / size |  |  |  | Pass / fail |
| Removal |  |  |  | Pass / fail |

## 12. Update And Monitoring Policy

```md
Dependency owner:
Update mechanism:
Allowed version range:
Automated update policy:
Required checks on update:
Advisory monitoring:
Maximum patch lag:
Maximum major-version lag:
Review cadence:
Emergency contact:
```

An automated update PR is a proposal. It still needs evidence proportional to the package's permissions and consequence.

## 13. Exit Plan

```md
Removal trigger:
Replacement trigger:
Data export requirement:
Provider-specific data to migrate:
Adapter or files to delete:
Configuration and secrets to revoke:
Transitive dependencies expected to leave:
Fallback behavior during removal:
Estimated removal effort:
Removal owner:
Last uninstall test:
```

### Exit Triggers

- [ ] Maintenance or security response falls below policy.
- [ ] Product use no longer justifies the trust surface.
- [ ] Platform capability replaces the dependency.
- [ ] License, pricing, privacy, or terms materially change.
- [ ] Bundle, performance, or reliability cost exceeds budget.
- [ ] A simpler dependency or local implementation becomes preferable.
- [ ] The integration boundary no longer contains vendor coupling.

## 14. Decision

```md
Decision: [adopt / trial / adopt with conditions / reject / defer]
Version or digest approved:
Conditions:
Accepted unknowns:
Rejected alternatives:
Owner:
Approvers:
Approval date:
Review date:
Related PR / ADR / ticket:
```

---

## Worked Example: Schema Validation Library

```md
Need: Validate untrusted API payloads at runtime and return field-level errors.

Suggestion provenance: An AI assistant proposed three packages. A developer
verified each against the official registry and source repository before review.

Alternatives: Hand-written guards were rejected because the schema changes
frequently. The existing type checker cannot validate runtime data.

Identity: Exact scoped package, registry, repository, publisher, version, and
lockfile entries match. Install scripts: none. Native binaries: none.

Permissions: Application memory only. No network, filesystem, telemetry, or
secrets required at runtime.

Boundary: One adapter translates validation output into product-domain errors.
Vendor types do not cross the adapter.

Verification: Malformed, missing, oversized, and unexpected fields tested.
Bundle delta measured. Dependency and license scans passed under team policy.

Exit: Replace the adapter implementation, remove package and lockfile entries,
run contract tests, and confirm the transitive tree returns to baseline.

Decision: Adopt pinned minor line with automated patch proposals, required CI,
and a six-month ownership review.
```

## Prompt For An AI Agent

```md
Use this Dependency Adoption Receipt to review the proposed dependency below.

1. Restate the required capability without naming the dependency.
2. Verify that identity, publisher, version, registry, and source evidence agree.
3. Compare platform, existing-dependency, local, and third-party options.
4. Map direct and transitive code, install behavior, permissions, and data flows.
5. Identify security, license, maintenance, performance, and lock-in unknowns.
6. Propose proportionate verification and explicit stop conditions.
7. Design a narrow integration boundary and executable removal plan.
8. Separate verified facts from inferences and unresolved questions.
9. Do not run install commands, modify lockfiles, or approve adoption without human authorization.

Dependency context:
[PASTE PACKAGE, REQUIREMENT, AND PROJECT CONTEXT]
```

## Research Basis

- [OpenSSF Security-Focused Guide for AI Code Assistant Instructions](https://best.openssf.org/Security-Focused-Guide-for-AI-Code-Assistant-Instructions)
- [SLSA 1.2 specification and provenance model](https://slsa.dev/spec/v1.2/)
- [SLSA guidance for verifying artifacts](https://slsa.dev/spec/v1.2/verifying-artifacts)
- [SPDX specification](https://spdx.dev/use/specifications/)
- [OWASP CycloneDX SBOM guidance](https://cyclonedx.org/guides/sbom/bom)

The receipt is a decision record, not an attestation. Prefer machine-verifiable SBOM, signature, provenance, vulnerability, and test evidence wherever the ecosystem supports it.