Skip to content

Upstream Synchronization Standard

Purpose

This standard governs how Bluefly integrates, documents, and synchronizes with external technologies and upstream projects (e.g., Gas City, Dolt, OSSA). The goal is to keep upstream behavior authoritative at the upstream source, avoid documentation drift, and clearly separate upstream facts from Bluefly's internal strategy and composition.

Core Rules

1. No Verbatim Copying of Upstream Documentation

  • Do not copy installation guides, configuration schemas, or command references from upstream sources into Bluefly repositories.
  • Upstream documentation is the sole authority for tool operation.
  • Why: Duplicated documentation inevitably drifts out of sync, leading to misconfiguration, agent hallucinations, and degraded system integrity.
  • Always provide direct links to the official upstream repositories, documentation sites, and release notes.
  • Use upstream-documented version constraints or lockfiles when referencing upstream capabilities.

3. Document Bluefly Interpretations and Deviations

  • Bluefly documentation is restricted to describing composition, strategy, and policy.
  • When documenting an upstream tool, use the Upstream Fact -> Bluefly Integration Note pattern.
  • Upstream Fact: State what the tool is and link to its docs.
  • Bluefly Integration Note: Explain only how Bluefly composes or utilizes the tool without redefining upstream behavior.

4. Periodic Re-verification

  • Upstream dependencies and their corresponding integration assumptions must be re-verified after every major upstream release.
  • Update the Authority Matrix and Upstream Dependency Ledger to reflect changes in upstream sources.
  • Public doc sites lag installed releases — verify version-sensitive claims against a live --version check, not doc-site text. Re-verified 2026-07-27: docs.gascity.com states gc 1.1.1 (tutorials) / v1.4.0 (install example) against an Oracle-installed gc 1.3.2; docs.gascityhall.ai states gt v0.5.0 against an Oracle-installed gt version 1.2.1 — over a full major version behind. Treat the public docs as authoritative for concepts/behavior, not for current version numbers.

5. Upstream Deployment Topology Inference

  • Only deploy components that upstream documents as part of the supported runtime.
  • Do not infer deployment topology from repository names, GitHub organization layout, or code structure (e.g., assuming every repository is a standalone Docker service).
  • Treat all repositories as libraries, CLI tools, or plugins that run inside a primary gateway unless upstream officially declares them as standalone services.

Upstream Capability Admission Gate (binding)

Every Open Source / upstream integration SHALL pass these phases in order. Bluefly code that implements domain-specific behavior is Phase 5 only.

Phase Name Required output
0 Discover upstream Named product, official docs URL, CLI/API owner
1 Capability audit Evidence that native functionality, config, plugin, provider, middleware, extension point, or supported integration was searched
2 Ownership map What upstream owns vs what Bluefly may compose (single authority per capability)
3 Native implementation Prefer upstream commands/config as designed — no wrappers that reimplement
4 Extension points Use only documented hooks/providers/plugins
5 Bluefly adapter Only if Phases 1–2 prove a gap; adapter must cite the gap evidence

Hard gate: If Phase 1 and Phase 2 artifacts with evidence are missing, Phase 5 is forbidden.

Upstream checkouts: Under Knowledge/Upstream-Repos/ (and equivalent read-only mirrors), engineers MAY git pull the latest published revision. Engineers SHALL NOT modify upstream source trees, commit to them, or patch them in place. Gaps are closed via Bluefly adapters or upstream contribution — never by editing the mirror.

Recovery operations: Prefer upstream recovery commands (e.g. bd bootstrap) over Bluefly reimplementation. Capture pre/post receipts with upstream diagnostics only.

Repository Authority — Gas City family (VERIFIED 2026-07-21; correction added 2026-07-27)

Canonical local mirrors: /Volumes/AgentPlatform/Knowledge/Upstream-Repos/gascityhall/

(Directory name is gascityhall, not gascity. Do not create a parallel path.)

Authoritative for GasCity, GasCity, Beads, GasCity Official Docs, and related repos under that tree.

Correction (re-verified 2026-07-27): these subdirectories are NOT independent git clones. Each one (gascity/, gascity/, beads/, GasCity-Official-Docs/, etc.) has no .git of its own — git -C <subdir> rev-parse --show-toplevel resolves to /Volumes/AgentPlatform/Knowledge, and every subdirectory reports the same single commit and the same remote (blueflyio.wiki.git). They are static copies tracked inside the Knowledge wiki repo, not per-repo mirrors with their own upstream remote/history. The "verify the mirror exists → git pull" step below does not do what it says: a git pull here refreshes the Knowledge wiki repo, not any individual upstream project. Until this is re-architected (e.g., real clones or git submodules per upstream repo), treat content under this tree as a point-in-time snapshot (last touched 2026-07-21) and cross-check version-sensitive claims live (see §4 Periodic Re-verification) rather than assuming git pull here fetches fresh upstream state.

Docs / curation standing rule

Before analyzing any upstream project: verify the mirror exists → git pull → record Evidence Log → analyze that commit. Never create a new clone when an authoritative mirror already exists. Never clone upstream into BluCity-Docs.

Evidence Log (required)

Repository:
Branch:
Commit:
Last Pull:
Analysis Date:
Documentation Version:

BluCity-Docs role

GitHub → Upstream-Repos (evidence) → Capability Inventory → Ownership Analysis → BluCity-Docs (curated interpretation)

BluCity-Docs is not an upstream mirror.

Enforcement

Any pull request or documentation update that violates these rules (e.g., by pasting upstream API responses or CLI help text) will be rejected. Agents and engineers must rely on the upstream authority for implementation details.