Skip to content

ADR-0008: Where should Bluefly maintain read-only upstream authorities?

Status

Candidate — OPEN. Do not standardize a directory name (e.g. upstream-references/) until this ADR is accepted.

Context

Bluefly integrates many upstream authorities whose behavior Bluefly does not own:

Domain Upstream authority Current Bluefly pointer (OBSERVED)
Gas City https://docs.gascityhall.ai/ upstream-lawbooks.md
Gas City https://docs.gascity.com/ upstream-lawbooks.md
Beads / Dolt https://beads.gascity.com/ Capability/durable-work/beads/
OpenClaw https://github.com/openclaw/openclaw upstream-lawbooks.md
Anthropic / Claude Vendor docs UNKNOWN — no canonical pointer verified
GitLab https://docs.gitlab.com/ UNKNOWN — scattered ES references
DDEV https://ddev.readthedocs.io/ UNKNOWN — capability stub only
Drupal https://www.drupal.org/docs ES Drupal standards
OCI / Oracle Cloud Vendor docs UNKNOWN
Tailscale https://tailscale.com/kb/ UNKNOWN

RETRIEVED: library/README.md defines references/upstreams/ under Library lifecycle — not yet verified as populated.

INFERRED: Duplicated upstream paraphrase across library/, Engineering-Standard/, and Evidence/ creates drift. Evidence reorganized by capability (Evidence/Capability/) separates upstream facts (UP-) from Bluefly receipts (RX-).

Decision drivers

  1. One authority, many projections — link, do not rewrite.
  2. Agents must resolve upstream URL before writing local doctrine.
  3. Capability-based Evidence must not sprawl into full manual copies.
  4. ZACA / convergence audit before bulk moves (library/README.md § Upstream-first).

Options (not selected)

Option Description Tradeoffs
O1 — library/references/upstreams/ Lifecycle library class reference_only per existing library standard. Human-friendly; may blur with canon if mis-tagged.
O2 — Evidence/Capability/<capability>/ RETRIEVED stubs only; no prose manuals. Matches operator Evidence layout; not a full URL index.
O3 — Central upstream-references/ root Single directory name at repo root. Deferred — operator forbids standardizing name until ADR closes.
O4 — Engineering-Standard reference/ only CLI and integration boundaries. Already owns boundaries; poor fit for vendor doc links.
O5 — External index only (qmd, llms.txt) No local copies; query-time resolution. Requires qmd corpus maintenance; offline gap.
O6 — Per-product doc trees e.g. Products/*/docs/upstream. Rejected (INFERRED) — violates capability-not-product Evidence rule.

Questions (open)

  1. Should RETRIEVED stubs live only under Evidence/Capability/ with library/references/upstreams/ as a thin URL index?
  2. How are Anthropic, GitLab, OCI, and Tailscale registered without new sprawl paths?
  3. Does upstream-lawbooks.md remain the Gas City/OpenClaw/Beads index of record with capability folders holding receipt-linked facts only?
  4. What promotion path moves a RETRIEVED stub to canon vs archive?

Decision

OPEN — UNKNOWN

No directory name is standardized. Agents MUST:

  • Link upstream URL in any new evidence stub.
  • Tag claims RETRIEVED|OBSERVED|INFERRED|NOT_FOUND|UNKNOWN.
  • Avoid creating parallel upstream manuals in Bluefly repos.

Consequences (provisional)

References