---
id: canon-contrib-convention
type: standard
title: "Contribution Convention v0.1"
domain: custodian
status: active
version: "0.1"
created: "2026-02-28"
---

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

```yaml
---
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: custodian | railiance | markitect | ...    # originating domain
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)

```yaml
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)

```yaml
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)

```yaml
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)

```yaml
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.