## 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.