Feat/documentation and governance improvements

CHANGELOG.md

@@ -7,9 +7,21 @@ and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) conventions.
 Commit message format is enforced via [commitlint](https://commitlint.js.org/) starting with v0.2.0.
 
 > **How to update this file**
-> Run `npm run generate:client` after any API surface change and bump the version
-> in `package.json`. Add your changes under `[Unreleased]` as you work; entries
-> are moved to a versioned section on release.
+>
+> Add entries to the `[Unreleased]` section as you work on features and fixes.
+> Organize by subsection (`Added`, `Fixed`, `Removed`, etc.) as defined below.
+>
+> **Mapping from Conventional Commits:**
+> - `feat(scope): ...` → `[Added]`
+> - `fix(scope): ...` → `[Fixed]`
+> - `perf(scope): ...` → `[Changed]` (with note about performance improvement)
+> - `refactor(scope): ...` → `[Changed]` (with scope of refactoring)
+> - `docs(scope): ...` → `[Documentation]` (if user-facing; skip if internal only)
+> - `chore(scope): ...` → Skip (internal tooling, no user-visible change)
+>
+> On version release, the `[Unreleased]` section is renamed to `[X.Y.Z]` with the
+> release date, and a new `[Unreleased]` section is created. Version must be bumped
+> in `package.json` to match.
 
 ---
 

CONTRIBUTING.md

@@ -382,6 +382,81 @@ The CI job `commitlint` checks the PR title on every pull request. Squash
 merges are preferred so that the merge commit title is the canonical changelog
 entry.
 
+### Updating the changelog
+
+When working on a feature or fix that affects users, add an entry to `CHANGELOG.md`
+under `[Unreleased]` before opening your PR:
+
+| Commit Type | Changelog Section | Example |
+|-------------|-------------------|---------|
+| `feat(...)` | `Added` | A new endpoint or behavior |
+| `fix(...)` | `Fixed` | A bug fix or behavioral correction |
+| `perf(...)` | `Changed` | Performance improvement |
+| `refactor(...)` | `Changed` | Major structural change affecting users |
+| `docs(...)` | `Documentation` | User-facing documentation changes |
+| `chore(...)` | — | Skip (internal tooling, no user-visible change) |
+| `test(...)` | — | Skip (internal tests, no user-visible change) |
+
+For details on changelog format and section definitions, see the instructions in
+`CHANGELOG.md`.
+
+---
+
+## GitHub issue labels
+
+When creating or triaging GitHub Issues, use the label taxonomy defined in
+[docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md) to categorize work by difficulty
+and area. This helps contributors discover work that matches their skill level and
+interest.
+
+### Quick reference
+
+- **`good-first-issue`** — Suitable for newcomers; isolated, self-contained, no major
+  prerequisites blocking
+- **`help-wanted`** — Open to anyone; clear scope but could benefit from fresh eyes
+- **`category/*`** — Categorize by area: `category/backend`, `category/security`,
+  `category/devops`, `category/governance`
+- **`status/*`** — Track lifecycle: `status/in-progress`, `status/blocked`,
+  `status/ready-to-merge`
+
+For detailed mapping rules (e.g. how to label issues from the contributor backlog),
+see [docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md).
+
+## Drips Wave contributor accounting
+
+This project offers a points-based contributor incentive program (Drips Wave).
+Contributors who close issues earn points that are recorded in a ledger.
+
+### How points are awarded
+
+Every issue in the contributor backlog has a fixed point value:
+- **High complexity**: 200 points
+- **Medium complexity**: 150 points
+
+When your PR closes an issue, the points for that issue are credited to your contributor account.
+See [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md) for the full ledger and accounting rules.
+
+### For PR authors
+
+When you open a PR that solves an issue from the backlog, include a `Closes` tag in your
+PR description to link the PR to the issue number:
+
+```markdown
+## Description
+
+Brief description of the changes.
+
+Closes #<issue-number>
+```
+
+This creates an auditable record that ties your PR to a specific point value. The ledger
+is updated when the PR is merged.
+
+### Disputes and escalation
+
+If there's a disagreement about points, attribution, or the ledger record, see the
+escalation process in [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md).
+
 ---
 
 ## Submitting a pull request

docs/DRIPS_WAVE_LEDGER.md

@@ -0,0 +1,65 @@
+# Drips Wave Contributor Ledger
+
+This document records contributions to the vortex-backend contributor incentive program (Drips Wave), tracking issue numbers, contributors, merge dates, and points awarded.
+
+## Format
+
+| Merge Date | PR | Contributor | Issue Number | Issue Title | Points | Notes |
+|------------|-----|-------------|--------------|-------------|--------|-------|
+| YYYY-MM-DD | #XXX | @username | #N | Short description | 150/200 | Any special context |
+
+## Ledger
+
+### Phase 1 (Q3 2026)
+
+_(Initial seed batch — to be populated as first wave of issues are completed)_
+
+## Accounting Rules
+
+### Point Values
+
+- **High complexity**: 200 points
+- **Medium complexity**: 150 points
+
+Complexity levels are defined in `issues.md` (upstream) and referenced in GitHub Issue descriptions.
+
+### Source of Truth
+
+Each PR must reference an issue number in its description:
+```
+Closes #<issue-number>
+```
+
+This creates a verifiable link between the merged PR and the `issues.md` entry, enabling automated or manual ledger updates.
+
+### Recording Process
+
+1. **PR opens**: Author ensures the description includes `Closes #<issue-number>`
+2. **PR merged**: Merge commit title captures the change; the linked issue is the join key
+3. **Ledger update**: A maintainer (or automated CI job, if implemented) adds a row to this ledger
+
+The ledger is append-only; rows are not deleted or modified once recorded.
+
+### Dispute Resolution
+
+Disputes about point allocation or contributor attribution follow the escalation ladder in
+[CODE_OF_CONDUCT.md](https://github.com/vortex-protocol/.github/blob/main/CODE_OF_CONDUCT.md):
+
+1. **Clarification**: Poster of ledger entry and contributor agree on facts
+2. **Maintainer review**: If disagreement persists, a maintainer with push access reviews the issue and PR
+3. **Escalation**: Unresolved disputes are brought to the team lead for final decision
+
+Changes to the ledger (if any are needed) are documented in a follow-up commit with reasoning.
+
+## Notes
+
+- This ledger is not a replacement for contributor recognition elsewhere (e.g. GitHub's contributor graph, release notes)
+- Point totals do not automatically convert to payments or rewards; that is handled separately and outside this repository
+- Ledger entries are public and auditable; disputes and resolutions are also documented publicly
+
+---
+
+For more context on the Drips Wave program, see:
+- `issues.md` (upstream, in vortex-protocol/.github) — defines issues and point values
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — contributor workflow
+- `CHANGELOG.md` — user-facing changes

docs/LABEL_TAXONOMY.md

@@ -0,0 +1,77 @@
+# Label Taxonomy and Issue Management
+
+## Overview
+
+This document defines the label taxonomy for GitHub Issues, used to categorize contributor work from `issues.md` and help new contributors discover work that matches their skill level.
+
+## Label Categories
+
+### Difficulty Labels
+
+Used to indicate the expected difficulty and prerequisite knowledge for a given issue.
+
+| Label | Color | Description | Candidates |
+|-------|-------|-------------|-----------|
+| `good-first-issue` | `#7057ff` | Suitable for newcomers with no major prerequisites; isolated, self-contained scope | Medium complexity issues with no unresolved High-complexity prerequisites |
+| `help-wanted` | `#008672` | Open to anyone; may have a clear scope but could benefit from fresh eyes or bandwidth | Any complexity level without critical-path blocking |
+| `hard` | `#d73a49` | Significant challenge; may require deep codebase knowledge or non-trivial design work | High complexity issues; new architectural patterns |
+
+### Category Labels
+
+Mirror the four implicit categories in `issues.md`:
+
+| Label | Color | Description |
+|-------|-------|-------------|
+| `category/backend` | `#c2e0c6` | Backend API, services, database, integrations |
+| `category/security` | `#fc2929` | Security audit, vulnerability disclosure, authentication |
+| `category/devops` | `#1d76db` | Infrastructure, CI/CD, monitoring, operations |
+| `category/governance` | `#ffc274` | Community, documentation, process, contributor onboarding |
+
+### Status Labels
+
+Track issue lifecycle:
+
+| Label | Color | Description |
+|-------|-------|-------------|
+| `status/blocked` | `#d73a49` | Cannot proceed; describes blocker in the issue or comment |
+| `status/in-progress` | `#0075ca` | Being actively worked on; PR referenced in issue or comment |
+| `status/ready-to-merge` | `#a2eeef` | Approved PR awaiting merge; linked PR should reference issue number |
+
+## Mapping Rules
+
+### From `issues.md` to GitHub Issues
+
+When mirroring an issue from `issues.md` to GitHub:
+
+1. **Title**: Use the issue's `[DESCRIPTION]` line verbatim
+2. **Body**: Include the full `[DESCRIPTION]` + `[PROBLEM STATEMENT & CONTEXT]` sections; link back to `issues.md`
+3. **Category Label**: Determine from the issue's category in `issues.md`; apply one of `category/backend`, `category/security`, `category/devops`, or `category/governance`
+4. **Difficulty Label**: Apply based on Complexity + prerequisites:
+   - **`good-first-issue`**: If Complexity is `Medium` AND the issue description does not reference any High-complexity issue numbers as prerequisites
+   - **`help-wanted`**: If the issue is open and not currently assigned, and is not blocked by another open issue
+   - **`hard`**: If Complexity is `High`, always apply (in addition to category label)
+5. **Prerequisites**: In the issue body, add a "Prerequisites" section listing any dependent issues (those referenced in Implementation Guidelines or Problem Statement)
+
+**Example**: Issue #25 in `issues.md` is "Medium" complexity in Backend, doesn't reference a High blocker → `category/backend` + `good-first-issue`
+
+### Exclusion Rules
+
+Do **not** mark an issue as `good-first-issue` if:
+- Any of its prerequisites are still open
+- It requires significant cross-module refactoring
+- Its description includes "TODO: [document the unfinished design]" or similar
+
+## Maintenance
+
+- When an issue is closed (PR merged), remove the `help-wanted` label if present
+- When an issue moves to active work, add `status/in-progress` and reference the PR
+- When a PR is approved, add `status/ready-to-merge` (removed on merge)
+- Review labels quarterly as the backlog evolves
+
+## Initial Seed Batch
+
+The first batch of issues mirrored from `issues.md` (issues #316–#330) should include examples from all categories and both difficulty levels to establish a clear pattern for future contributors.
+
+---
+
+For more context on how the contributor backlog is managed, see [CONTRIBUTING.md](./CONTRIBUTING.md) and [issues.md](./issues.md) in the upstream repository.