Contribution Convention v0.1

Purpose

This document defines the canonical convention for tracking upstream contributions across all custodian-ecosystem repositories. A contribution is any intentional engagement with an external upstream project: a bug report, feature request, extension-point proposal, or pull request.

Contributions are tracked as Markdown artifacts with typed YAML frontmatter, committed to the repository that authors them, and indexed in the State Hub DB. This enables the Custodian to maintain a full audit trail of all upstream engagement across all six project domains.

Artifact Types

Code	Name	Description
`br`	Bug Report	A defect reported to an upstream project
`fr`	Feature Request	A capability requested from an upstream project
`ep`	Extension-Point Proposal	A proposed extension point in an upstream project
`upr`	Upstream PR	A pull request submitted or planned for upstream

Directory Layout

<repo-root>/
  contrib/
    bug-reports/       # BR artifacts
    feature-requests/  # FR artifacts
    extension-points/  # EP artifacts
    upstream-prs/      # UPR artifacts

Each artifact file follows the naming pattern:

<YYYY-MM-DD>--<org>--<repo>--<slug>.md

Examples:

contrib/bug-reports/2026-03-01--observablehq--framework--plot-tooltip-flicker.md
contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md
contrib/extension-points/EP-CUST-002--anthropic--claude-code--hook-on-tool-result.md

Frontmatter Schema

All contribution artifacts share a common base frontmatter:

---
id: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug>   # unique string ID
type: br | fr | ep | upr                           # required
target_org: <github-org-or-owner>                  # required
target_repo: <repository-name>                     # required
title: "Human-readable title"                      # required
status: draft | submitted | acknowledged | accepted | rejected | merged | withdrawn
domain: infotech | agents | communication | ...   # current sector domain; see Repo Classification Standard §6
related_workstream: <workstream-slug>              # optional
state_hub_contribution_id: <uuid>                  # set once registered in State Hub
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
---

BR — Bug Report (additional fields)

upstream_version: "1.2.3"          # version where bug was observed
reproduction_steps: |
  1. …
  2. …
expected: "What should happen"
actual: "What actually happens"
workaround: "Any known workaround"  # optional
upstream_issue_url: "https://…"     # optional — link once filed

FR — Feature Request (additional fields)

motivation: "Why this feature is needed"
proposed_api: |
  # Sketch of the proposed interface
alternatives: "What we do instead today"
upstream_issue_url: "https://…"     # optional

EP — Extension-Point Proposal (additional fields)

ep_id: EP-<DOMAIN>-NNN              # e.g. EP-RAIL-007
location: "src/file.ts:42"          # file:line in upstream where hook would live
proposed_interface: |
  # Interface or callback signature sketch
rationale: "Why this extension point is valuable"
upstream_issue_url: "https://…"     # optional

UPR — Upstream PR (additional fields)

local_component_path: "relative/path/in/this/repo"
target_upstream_file: "path/in/upstream/repo"
upstream_pr_url: "https://…"        # set once submitted
draft_pr_body: |
  ## Summary
  …

  ## Motivation
  …

ID Schemes

BR / FR / UPR: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug> — date-prefixed slug
EP: EP-<DOMAIN>-NNN where <DOMAIN> is uppercase (CUST, RAIL, MARK, etc.) and NNN is a zero-padded three-digit sequence per domain (EP-CUST-001, EP-CUST-002, …). This scheme is an extension of the Railiance EP convention defined in the staged-promotion-lifecycle workstream; this canon document is the authoritative master spec.

Status Lifecycle

draft → submitted → acknowledged → accepted → merged
                ↘             ↘
              rejected      withdrawn

draft: artifact created locally, not yet sent upstream
submitted: issue filed or PR opened upstream
acknowledged: upstream team has responded
accepted: upstream has agreed to the proposal
rejected: upstream has declined
merged: PR merged / fix released
withdrawn: we decided not to pursue

Relationship to State Hub

Once an artifact is registered via register_contribution() MCP tool or POST /contributions/ API, the State Hub assigns a UUID and returns it. That UUID is written back into state_hub_contribution_id in the frontmatter.

The State Hub is a read/cache layer — the Markdown file is always the authoritative source of truth. If the DB is reset, contributions can be re-ingested from the files.