docs: security contacts adr [CM-1325]

[mbani01]

This pull request adds a new architecture decision record (ADR-0009) that documents the design and implementation details for the security-contacts worker, which extracts, scores, and ingests security contact information for critical repositories. The ADR covers the tiered extraction hierarchy, confidence scoring, data reconciliation, GitHub API usage, write semantics, scheduling, and the on-demand ingestion path, as well as alternatives considered and associated risks. Additionally, the ADR is linked in the ADR index.

New ADR documenting security-contacts worker:

• Added docs/adr/0009-security-contacts-worker.md to comprehensively describe the architecture and decision process for the security-contacts worker, including extraction tiers, scoring, reconciliation, and operational details.
• Updated docs/adr/README.md to reference ADR-0009 in the ADR index.

[cursor]

PR Summary

Low Risk
Documentation-only change with no application, schema, or deployment impact.

Overview
Adds ADR-0010 (docs/adr/0010-security-contacts-worker.md) as the consolidated record for the security-contacts sub-worker and registers it in the ADR index.

The ADR documents the accepted design (not new runtime code in this PR): Temporal daily batch ingestion plus an on-demand single-PURL workflow; tiered extractors (A/B/D); reconciliation, junk filtering, and [0,1] confidence scoring with bands; GitHub rate-limit gateway behavior; soft-delete upsert writes, partial-pass merge rules, and refresh cadence; handle verification and CDP email resolution; API semantics (securityContacts: null vs []); alternatives rejected; and operational risks/trade-offs.

^{Reviewed by Cursor Bugbot for commit 2f107e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Pull request overview

Adds ADR-0009 documenting the security-contacts worker architecture and links it from the ADR index.

Changes:

• Documents extraction, scoring, persistence, scheduling, and reconciliation decisions.
• Records alternatives, consequences, and risks.
• Updates the ADR index.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
docs/adr/0009-security-contacts-worker.md	Adds the security-contacts ADR.
docs/adr/README.md	Links ADR-0009.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[joanagmaia]

LGTM, just a matter of updating the ADR id and good to merge

[joanagmaia]

Conflicting ADR with main

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (4)

docs/adr/0010-security-contacts-worker.md:43

• Tier D is described as implemented, but none of the named extractor files exist and processBatch.ts:50-57 registers only A1 through B2. No code under security-contacts emits a tier-D contact. Either add the D extractors before accepting this ADR or clearly mark this tier and all dependent claims as proposed/unimplemented.

| D | Top-3 committers (last 90 days) + repo owner profile; static Go ecosystem fallback | `topCommitters.ts`, `repoOwner.ts`, `registry/go.ts` |

docs/adr/0010-security-contacts-worker.md:67

• The documented Go fallback is not implemented: there is no registry/go.ts, no golang.org/g.co/vulnz contact source, and extractors/registry/index.ts:19-28 explicitly omits Go from FETCHERS. As written, Go repos can still receive an empty result, contrary to this accepted decision.

- **Go packages get a static ecosystem fallback**: Go has no registry manifest carrying contact
  metadata (the module proxy and pkg.go.dev expose none), so the Go fetcher makes no HTTP call and
  always emits two tier-D `security-team` contacts per the Go security policy —
  `security@golang.org` and the `https://g.co/vulnz` report form. At tier D they never outrank a
  real repo-level contact, and they don't suppress the committers/owner gate (which only checks
  for usable contacts above tier D), so a Go repo is never left with an empty answer.

docs/adr/0010-security-contacts-worker.md:207

• The worker exposes this on-demand workflow, but no API code invokes it. Repository-wide references to ingestSecurityContactsForPurlWorkflow are limited to its definition and worker re-export; getPackage.ts:41-54 simply returns null when contacts have not been evaluated. Please wire the API cache-miss path to the packages Temporal client, or document that the caller integration is still pending rather than saying the request triggers ingestion.

On the read side, the API contract distinguishes **`securityContacts: null`** (repo never
evaluated — `contacts_last_refreshed IS NULL`, which is what triggers the on-demand ingest) from
**`[]`** (evaluated, nothing found — no re-ingest until the daily retry). `packageConfidence` is
derived at read time as the band of the highest contact score, not stored.

docs/adr/0010-security-contacts-worker.md:280

• The single-writer assumption already has a second writer in this ADR: the on-demand workflow calls writeContacts independently of the scheduled batch. ScheduleOverlapPolicy.SKIP only serializes schedule actions; it does not prevent on-demand executions (or concurrent cache misses) from writing the same repo. Record and implement a per-repo serialization/locking strategy, or explicitly accept and analyze the concurrent-write behavior.

- **Single-writer assumption** — `writeContacts` takes no lock; correctness relies on the Temporal
  schedule (SKIP overlap) and heartbeat-based supersession keeping one writer per repo. A future
  second caller (e.g. a backfill script) must respect this or add locking.