Danijel Martinek
432a606411
Add repo-root .socket.json (critical=error, high=warn, medium/low=ignore) and extend the evaluate-library skill's 8-filter protocol to 9 filters by adding Filter 9 — Supply-chain behavior (Socket). Positions Socket last in Phase 2 (most expensive: network call), documents socket-cli as the verification command, and maps clean/flagged/<finding-summary> to the trace's socketRisk field. Updates short-circuit skip lists for all earlier Phase 2 filters and adds socketRisk to TRACE-TEMPLATE.md frontmatter.
5.5 KiB
5.5 KiB
Trace Template
Use this file as the structural guide when writing a library decision trace. Copy the frontmatter block and all 11 headings. Replace placeholder values with real results.
Trace path: docs/library-decisions/<YYYY-MM-DD>-<package-name>.md
Frontmatter — all filters evaluated
---
package: <npm-package-name>
version: "<semver range>"
tier: app | feature | core
decision: approved | rejected
date: <YYYY-MM-DD>
deciders: [<author>, ...]
adr: adr-NNN | null
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 | <finding-summary>
verification-commands:
- <literal command that produced the license result>
- <literal command that confirmed types>
- <literal command that checked maintenance>
- <literal command that ran the CVE scan>
accepted-cves: []
---
Frontmatter — partial trace (expensive filters short-circuited)
When an expensive filter fails (Phase 2 short-circuit), set remaining filter fields to skip. The Zod schema validates approved traces end-to-end; skip is the accepted sentinel for unevaluated fields in rejected traces.
Example: maintenance: abandoned → cve-scan, eu-residency, named-consumer skipped.
---
package: <npm-package-name>
version: "<semver range>"
tier: feature | core
decision: rejected
date: <YYYY-MM-DD>
deciders: [<author>, ...]
adr: null
filter-results:
license: MIT
types: native
maintenance: abandoned
boundary-fit: pass
shadow-check: pass
eu-residency: skip
cve-scan: skip
named-consumer: skip
socketRisk: skip
verification-commands:
- npm view <pkg> time.modified
accepted-cves: []
---
Required headings (11 total, in this order)
Filter sections (8)
## Filter: license
<!-- Result: <SPDX id> -->
Record the SPDX identifier from `package.json` or `npx license-checker --packages <pkg>`.
Allowed: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0.
Anything else → auto-reject (note the identifier and rejection reason).
## Filter: types
<!-- Result: native | @types/<x> | none -->
Confirm TypeScript types are available. `native` = ships its own `.d.ts`; `@types/<x>` = community
types package exists and is current; `none` = no types → auto-reject.
## Filter: maintenance
<!-- Result: active | dormant | abandoned -->
Check last release date and recent PR/issue activity. `active` = last release < 18 months AND
activity < 12 months. `dormant` = stable but not actively developed (acceptable for finished
libraries). `abandoned` = auto-reject.
If skipped (earlier expensive filter failed), write: "Not evaluated — skipped due to <filter> rejection."
## Filter: boundary-fit
<!-- Result: pass | fail -->
Confirm the dependency does not violate ESLint boundary-tag rules for the target tier
(ADR-006, ADR-010, ADR-017). Name the specific rule checked and the result.
## Filter: shadow-check
<!-- Result: pass | fail | "shadows <x>" -->
Check whether this library duplicates a must-have already locked in the workspace.
Locked must-haves: zod, inversify, payload, @trpc/server, superjson, reflect-metadata.
`shadows <x>` → auto-reject; a replacement requires a dedicated ADR.
## Filter: eu-residency
<!-- Result: ok | n/a | self-hostable | fail | skip -->
If the library transmits user data, telemetry, or business state to a vendor-controlled
endpoint by default, the vendor must offer an EU data region and the integration must be
configured to use it. Pure in-process libraries and build-time tools → `n/a`.
If skipped, write: "Not evaluated — skipped due to <filter> rejection."
## Filter: cve-scan
<!-- Result: clean | "<advisory-id>" | fail | skip -->
Run `pnpm audit --audit-level=moderate`. `clean` = no advisories at adoption time. Record
accepted advisory IDs in the `accepted-cves` frontmatter field and explain the risk acceptance
here. If skipped, write: "Not evaluated — skipped due to <filter> rejection."
## Filter: named-consumer
<!-- Result: pass | fail | skip -->
Answer: "Who calls this code path today, or who is blocked waiting for it?"
Hypothetical future callers are not consumers (ADR-022 §2.8 — the direct response to the
2026-05-14 OpenAPI near-miss). If skipped, write: "Not evaluated — skipped due to <filter> rejection."
Prompt sections (3)
## Prompt: replaces
<!-- Required: answer in either direction with justification -->
What existing library or approach does this replace? New-and-old running in parallel is a smell.
Name the thing being retired and its retirement plan, or explain why parallel adoption is
intentional and time-bounded.
## Prompt: migration-cost-out
<!-- Required: mechanical | hard | impossible + justification -->
What does ripping this back out look like 18 months from now? Rate: mechanical (swap package,
update call sites), hard (scattered integration, data-format dependencies), or impossible
(vendor lock-in, protocol coupling). Higher migration cost raises the adoption bar.
## Prompt: alternatives-considered
<!-- Required: minimum two named alternatives, or "none with explanation" -->
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.