feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs

Navigation:
- New order: Overview · Todo · Domains · Repos · Workstreams (collapsible,
  open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends,
  Dependencies) · Contributions · SBOM · Progress · Reference (collapsible)
- Reference section gains path:/reference landing page; all 18 doc pages
  listed in nav (alphabetical) and in reference.md table

New pages:
- todo.md — Internal / Ecosystem / Third-party todo classification
- dependencies.md — dependency edge table derived from state/summary
- reference.md — Reference landing page with full doc index

New reference doc pages (11):
  contributions, debt, dependencies, domains, extensions, overview,
  repos, tasks, todo + reference (meta) already added previously

doc-overlay.js — lazy bubblehelp tooltip:
- _titleCache Map + _fetchDocTitle(docPath): on first hover of any ?
  button, fetches the target doc page, parses <h1>, sets btn.title
- Native browser tooltip appears exactly on the ? circle on subsequent hover

Context-help wired on all 14 dashboard pages:
- h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept,
  extensions, dependencies (contributions/workstreams/decisions/sbom/
  progress/reference were already wired)
- domains.md + repos.md: added missing withDocHelp import and live-data link
- tasks/techdept/extensions: removed duplicate _h1 const that caused
  SyntaxError: Identifier '_h1' has already been declared

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-01 23:46:26 +01:00
parent 894c8b3934
commit 235355eb58
22 changed files with 1468 additions and 25 deletions

View File

@@ -0,0 +1,120 @@
---
title: Contributions — Reference
---
# Contributions — Reference
Contributions track **outbound upstream work** — things the Custodian has
identified that belong in a repo it does not own or control. Each contribution
is a structured artifact filed locally in the repo's `contrib/` directory and
registered in the state hub so it is never lost.
---
## Contribution types
| Type | Full name | Use when |
|------|-----------|----------|
| `br` | Bug Report | You found a defect in an upstream tool or library |
| `fr` | Feature Request | You need functionality that upstream does not yet provide |
| `ep` | Extension Point | You identified a future enhancement opportunity in upstream code |
| `upr` | Upstream PR | You have written (or are writing) a patch for an upstream repo |
---
## Lifecycle
```
draft → submitted → acknowledged → accepted → merged
↘ ↘
rejected withdrawn
```
| Status | Meaning |
|--------|---------|
| **draft** | Artifact written locally; not yet sent upstream |
| **submitted** | Filed as a GitHub issue, PR, or email — awaiting upstream response |
| **acknowledged** | Upstream has seen it and responded (e.g. triaged, commented) |
| **accepted** | Upstream agreed to take action |
| **merged** | PR accepted and merged; issue resolved |
| **rejected** | Upstream declined; record kept for future reference |
| **withdrawn** | We decided not to pursue it |
Transitions are enforced by the API — you cannot skip stages arbitrarily.
`submitted_at` is stamped automatically when status moves to `submitted`;
`resolved_at` is stamped when status moves to `merged`, `rejected`, or `withdrawn`.
---
## Relation to the Todo classification
Contributions map directly to the **Third-party** class in the inter-repo
communication taxonomy:
| Todo class | Mechanism |
|------------|-----------|
| Internal | Workplan file + task in this repo's workstream |
| Ecosystem | State hub task with `[repo:<slug>]` prefix |
| **Third-party** | **Contribution artifact in `contrib/` + state hub registration** |
Contributions in `draft`, `submitted`, or `acknowledged` status appear as
open Third-party todos on the [Todo](/todo) page.
---
## File layout
Each artifact lives in the current repo under `contrib/`:
```
contrib/
bug-reports/ br-YYYY-MM-DD--<org>--<repo>--<slug>.md
feature-requests/ fr-YYYY-MM-DD--<org>--<repo>--<slug>.md
extension-points/ EP-<DOMAIN>-NNN--<org>--<repo>--<slug>.md
upstream-prs/ upr-YYYY-MM-DD--<org>--<repo>--<slug>.md
```
Templates live in `~/the-custodian/canon/standards/contrib-templates/`.
Convention details: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`.
---
## Adding a contribution
**1. Write the artifact file** using the appropriate template.
**2. Register it in the state hub** via MCP:
```
register_contribution(
type = "fr",
title = "Add sidebar TOC injection API",
target_org = "observablehq",
target_repo = "framework",
body_path = "contrib/feature-requests/fr-2026-02-26--observablehq--framework--toc.md",
related_workstream_id = "<uuid>"
)
```
**3. Close the loop** when you file it upstream:
```
update_contribution_status(contribution_id="<uuid>", status="submitted")
```
**4. Keep updating** as upstream responds — `acknowledged`, `accepted`, `merged`.
---
## Kanban board
The Contributions page groups artifacts by status column. Only columns with at
least one entry are shown. The **⚠ follow-up banner** appears when any
contribution has been in `submitted` or `acknowledged` for an extended period
without further movement — a prompt to check in with upstream.
---
*Contributions are append-only. Rejected or withdrawn artifacts are retained as
institutional memory — they explain why certain approaches were tried and
dropped.*