docs/roadmaps/musehub-taxonomy.md · gabriel/musehub

- [ ] Issues with labels: `bug`, `enhancement`, `question`, `analysis`, `merge-conflict`, `needs-arrangement`, `help-wanted`, `good-first-issue`, `musical-theory`, `performance`

711

- [ ] Issues assigned to multiple users

712

- [ ] Issues linked to milestones

713

- [ ] Issues with sub-tasks (markdown checkboxes in body)

714

- [ ] Cross-repo references (`owner/repo#N`)

715

- [ ] Issues closed by PR ("Closes #N" in PR body)

716

717

#### musehub_issue_comments

718

Minimum **5 comments per issue**:

719

- [ ] Comments with markdown formatting

720

- [ ] Comments with code blocks (MIDI snippet representations)

721

- [ ] Comments with musical notation references

722

- [ ] Threaded replies (`parent_id` set)

723

- [ ] Comments with @mentions

724

- [ ] Comments with reactions

725

726

#### musehub_milestones

727

Per repo:

728

- [ ] 3-5 milestones (v0.1, v0.2, v1.0, "Bach Complete", "EDM Edition", etc.)

729

- [ ] Mix of open / closed

730

- [ ] With and without `due_on` dates

731

- [ ] Linked to multiple issues

732

733

#### musehub_pull_requests

734

Minimum **8 PRs per repo**:

735

- [ ] Open PRs (awaiting review)

736

- [ ] Merged PRs (`merged_at` set, `merge_commit_id` set)

737

- [ ] Closed PRs (rejected without merge)

738

- [ ] Cross-genre "merge conflict" PRs (EDM bassline into classical piece)

739

- [ ] PRs with detailed musical diff descriptions

740

- [ ] PRs with linked issues (Closes #N)

741

- [ ] PRs with multiple review comments

742

743

#### musehub_pr_comments

744

Per PR, 3-8 inline review comments:

745

- [ ] General comments (`target_type: "general"`)

746

- [ ] Track-specific comments (`target_type: "track"`, `target_track: "piano"`)

747

- [ ] Region comments with beat range (`target_type: "region"`, `target_beat_start`, `target_beat_end`)

748

- [ ] Note-specific comments (`target_type: "note"`, `target_note_pitch: 60`)

749

- [ ] Threaded replies (`parent_comment_id` set)

750

751

#### musehub_releases

752

Per repo, 3-5 releases:

753

- [ ] Semantic versions: v0.1.0, v0.2.0, v1.0.0

754

- [ ] Release notes with markdown (what changed musically)

755

- [ ] `download_urls` with all package types: `midi_bundle`, `stems`, `mp3`, `musicxml`, `metadata`

756

- [ ] Pre-release and latest badges

757

- [ ] Releases linked to commits

758

759

#### musehub_sessions

760

Per repo, 5-10 sessions:

761

- [ ] Solo sessions (1 participant)

762

- [ ] Duo sessions (2 participants)

763

- [ ] Full-band sessions (4-6 participants)

764

- [ ] Sessions with `intent` (what the session was trying to achieve)

765

- [ ] Sessions with `notes` (what happened, discoveries, blockers)

766

- [ ] Sessions linked to commits (commits made during that session)

767

- [ ] Active sessions (1 per repo marked `is_active: true`)

768

- [ ] Sessions at different locations (home studio, studio, remote collaboration)

769

770

#### musehub_webhooks

771

Per repo, 1-3 webhooks:

772

- [ ] Webhook for `push` events (CI simulation)

773

- [ ] Webhook for `pull_request` events

774

- [ ] Webhook for `release` events (notify downstream consumers)

775

- [ ] Fernet-encrypted secrets

776

- [ ] Mix of active / inactive

777

778

#### musehub_webhook_deliveries

779

Per webhook, 5-20 deliveries:

780

- [ ] Successful deliveries (response_status: 200)

781

- [ ] Failed deliveries (response_status: 500, 404, 0 for timeout)

782

- [ ] Multiple retry attempts (`attempt`: 1, 2, 3)

783

784

#### musehub_render_jobs

785

Per repo, 5-15 render jobs:

786

- [ ] Completed jobs (status: "done", mp3_object_ids populated)

787

- [ ] Failed jobs (status: "failed", error_message set)

788

- [ ] Pending jobs (status: "pending")

789

- [ ] Jobs with multiple MIDI files (midi_count > 1)

790

791

#### musehub_events

792

Per repo, 20+ activity events:

793

- [ ] `push` events

794

- [ ] `pull_request.opened`, `pull_request.merged`, `pull_request.closed`

795

- [ ] `issue.opened`, `issue.closed`

796

- [ ] `release.published`

797

- [ ] `star` events (when users star)

798

- [ ] `fork` events

799

- [ ] `member.added` events (collaborator added)

800

- [ ] `session.started`, `session.ended`

801

802

#### Social Tables

803

- [ ] **musehub_stars**: Every user stars 3-8 repos (not their own)

804

- [ ] **musehub_watches**: Every user watches 4-10 repos

805

- [ ] **musehub_follows**: Rich follow graph (each user follows 3-6 others)

806

- [ ] **musehub_forks**: 2-4 forks per public repo, cross-genre where possible

807

- [ ] **musehub_comments**: 3-8 comments per commit/release/PR

808

- [ ] **musehub_reactions**: Full emoji set on commits, issues, comments (👍 ❤️ 🎵 🔥 🎹 👏 🤔 😢)

809

- [ ] **musehub_notifications**: 10-20 unread notifications per user

810

- [ ] **musehub_view_events**: 30-100 view events per repo (simulates real traffic)

811

- [ ] **musehub_download_events**: 5-20 download events per release

812

813

### 4.8 Dramatic Narrative Scenarios (for Rich Seed Data)

814

815

The seed data should tell actual stories:

816

817

1. **"The Bach Remix War"** — `marcus` forks `bach/well-tempered-clavier`, adds trap drums and 808 bass, opens PR back to `bach`. `yuki` leaves detailed analysis comments about harmonic integrity. `bach` (auto) closes the PR. Heated issue thread ensues. Eventually a compromise branch emerges.

818

819

2. **"Chopin Meets Coltrane"** — `aaliya` forks `chopin/nocturnes`, reharmonises Nocturne Op.9 No.2 with Coltrane changes. 3-way merge conflict when `gabriel` also forks and adds jazz voicings. Beautiful merge commit resolves the conflict.

820

821

3. **"The Ragtime EDM Collab"** — `marcus` and `fatou` open a collaborative session on `marcus/ragtime-edm`. 8-commit session, 3 participants, ends with a release "v1.0.0 - Maple Leaf Drops".

822

823

4. **"Community Collab Chaos"** — `gabriel/community-collab` has all 10 users contributing. Multiple open PRs from different users, some conflicting, some cleanly merged. An open issue "Resolve the key signature — are we in G major or E minor?" with 20+ comments and a heated debate.

824

825

5. **"The Goldberg Milestone"** — `bach/goldberg-variations` has milestone "All 30 Variations Complete". Issues track each variation as a task. 28/30 closed. 2 still open and hotly debated.

---

## 5. GITHUB ISSUE BACKLOG

830

831

> Each item below should become one GitHub issue with appropriate labels.

832

> Labels: `feature`, `missing-url`, `seed-data`, `analysis`, `ui`, `api`, `muse-command`

833

834

### GROUP A — Missing MuseHub URLs (UI Implementation)

835

836

- [ ] **A-01**: `GET /{owner}/{repo}/blame/{ref}/{path}` — Implement muse blame UI page with per-note authorship visualization

837

- [ ] **A-02**: `GET /{owner}/{repo}/milestones` — Milestone list page with progress bars and issue linking

838

- [ ] **A-03**: `GET /{owner}/{repo}/milestones/{number}` — Milestone detail page with filtered issue list

839

- [ ] **A-04**: `GET /{owner}/{repo}/labels` — Label management page (create, edit, delete, colour picker)

840

- [ ] **A-05**: `GET /{owner}/{repo}/stash` — Stash list page with apply/pop/drop actions

841

- [ ] **A-06**: `GET /{owner}/{repo}/forks` — Fork network visualization page

842

- [ ] **A-07**: `GET /{owner}/{repo}/settings` — Repo settings page (visibility, description, tags, danger zone)

843

- [ ] **A-08**: `GET /{owner}/{repo}/webhooks` — Webhook management UI (list, create, test, delete)

844

- [ ] **A-09**: `GET /{owner}/{repo}/similarity/{base}...{head}` — Musical similarity score page

845

- [ ] **A-10**: `GET /{owner}/{repo}/emotion-diff/{base}...{head}` — Emotional delta visualization page

846

- [ ] **A-11**: `GET /{owner}/{repo}/analysis/{ref}/harmony` — Full harmonic analysis sub-page (Roman numerals, cadences)

847

- [ ] **A-12**: `GET /{owner}/{repo}/recall` — Semantic memory search over commit history

848

- [ ] **A-13**: `GET /notifications` — Notification inbox page with group/filter/mark-read

849

- [ ] **A-14**: `GET /users/{username}/followers` — Follower list page

850

- [ ] **A-15**: `GET /users/{username}/following` — Following list page

851

- [ ] **A-16**: `GET /topics/{tag}` — Topic browse page (repos grouped by tag)

852

- [ ] **A-17**: `GET /new` — New repo wizard UI

853

854

### GROUP B — Missing API Endpoints

855

856

- [ ] **B-01**: `GET/POST/PATCH/DELETE /api/v1/musehub/repos/{id}/milestones/{n}` — Full milestone CRUD API

857

- [ ] **B-02**: `GET/POST /api/v1/musehub/repos/{id}/labels` + `PATCH /issues/{n}/labels` — Label management API

858

- [ ] **B-03**: `GET /api/v1/musehub/repos/{id}/analysis/{ref}/harmony` — Harmonic analysis endpoint

859

- [ ] **B-04**: `GET /api/v1/musehub/repos/{id}/analysis/{ref}/similarity?compare={ref2}` — Similarity score endpoint

860

- [ ] **B-05**: `GET /api/v1/musehub/repos/{id}/analysis/{ref}/emotion-diff?base={ref}` — Emotion delta endpoint

861

- [ ] **B-06**: `GET /api/v1/musehub/repos/{id}/analysis/{ref}/recall?q={query}` — Semantic recall endpoint

862

- [ ] **B-07**: `GET/PATCH /api/v1/musehub/repos/{id}/settings` — Repo settings read/write

863

- [ ] **B-08**: `DELETE /api/v1/musehub/repos/{id}` — Repo deletion with cascade

864

- [ ] **B-09**: `POST /api/v1/musehub/repos/{id}/transfer` — Transfer repo ownership

865

- [ ] **B-10**: `GET/POST/DELETE /api/v1/musehub/repos/{id}/collaborators` — Collaborator management

866

- [ ] **B-11**: `GET /api/v1/musehub/repos/{id}/blame/{ref}` — Blame output as JSON for agents

867

- [ ] **B-12**: `GET/POST/DELETE /api/v1/musehub/repos/{id}/stash` + pop endpoint — Stash API

868

- [ ] **B-13**: `GET /api/v1/musehub/users/{username}/activity` — Public activity feed for a user

869

- [ ] **B-14**: `GET /api/v1/musehub/topics/{tag}/repos` — Repos by topic tag

870

871

### GROUP C — Per-Page UI Enhancements

872

873

- [ ] **C-01**: Explore page — Add filter sidebar (genre, key, tempo range, license, instrument)

874

- [ ] **C-02**: Explore page — Inline audio preview on repo card hover

875

- [ ] **C-03**: Repo landing — Contributor avatar grid with commit counts

876

- [ ] **C-04**: Repo landing — Activity contribution heatmap graph

877

- [ ] **C-05**: Repo landing — Instrument breakdown bar chart

878

- [ ] **C-06**: Repo landing — Clone URL widget with copy button

879

- [ ] **C-07**: Repo landing — README markdown rendering

880

- [ ] **C-08**: Commits list — Filter by author, date range, tag annotation

881

- [ ] **C-09**: Commits list — Per-commit instrument change badges + tempo/key metadata chips

882

- [ ] **C-10**: Commits list — "Compare" multi-select mode for picking two commits to diff

883

- [ ] **C-11**: Commit detail — Inline audio player (render_preview for the commit)

884

- [ ] **C-12**: Commit detail — Reactions and comments thread on commit

885

- [ ] **C-13**: PR list — Filter by assignee, label, milestone; sort options

886

- [ ] **C-14**: PR detail — Approval status per reviewer; review request workflow

887

- [ ] **C-15**: PR detail — Audio A/B inline player (base vs head)

888

- [ ] **C-16**: PR detail — Merge options: merge commit / squash / rebase selector

889

- [ ] **C-17**: Issue list — Filter by label, milestone, assignee; bulk actions

890

- [ ] **C-18**: Issue detail — Reactions on body and comments; threaded replies

891

- [ ] **C-19**: Issue detail — Timeline view (events + comments interspersed)

892

- [ ] **C-20**: Release detail — Embedded audio player + download stats

893

- [ ] **C-21**: Releases — RSS feed link + subscribe to releases button

894

- [ ] **C-22**: Analysis dashboard — Historical trend charts over commit history

895

- [ ] **C-23**: Analysis dashboard — "Analysis delta since parent commit" indicators

896

- [ ] **C-24**: User profile — Contribution heatmap graph (GitHub-style)

897

- [ ] **C-25**: User profile — Achievement badges system

898

- [ ] **C-26**: Insights — Full analytics suite (commit frequency, PR merge rate, fork growth)

899

900

### GROUP D — Muse Command UI Exposure (Missing)

901

902

- [ ] **D-01**: `muse amend` — UI button on commit detail page: "Amend last commit"

903

- [ ] **D-02**: `muse cherry-pick` — UI button on commit detail: "Apply to branch…"

904

- [ ] **D-03**: `muse revert` — UI button on commit detail: "Revert this commit"

905

- [ ] **D-04**: `muse rebase -i` — Interactive rebase UI (drag-to-reorder commits)

906

- [ ] **D-05**: `muse stash` — Stash panel in sidebar: push, list, apply, drop

907

- [ ] **D-06**: `muse bisect` — Bisect wizard UI: "Find the bad commit" binary search workflow

908

- [ ] **D-07**: `muse transpose` — UI control on commit/branch: "Transpose to key…"

909

- [ ] **D-08**: `muse tempo-scale` — UI control: "Time-stretch by factor…"

910

- [ ] **D-09**: `muse humanize` — UI toggle on commit: "Apply humanization"

911

- [ ] **D-10**: `muse validate` — UI badge on commit: "MIDI structure valid ✓"

912

- [ ] **D-11**: `muse import` — Repo UI: "Import MIDI file" → creates commit

913

- [ ] **D-12**: `muse describe` — Standalone page at `/{owner}/{repo}/describe/{ref}` with AI prose summary

914

- [ ] **D-13**: `muse recall` — Search UI: "Search musical memory" (semantic search over history)

915

- [ ] **D-14**: `muse resolve` — Merge conflict resolution UI with ours/theirs/manual options

916

- [ ] **D-15**: `muse worktree` — Worktree list UI: see all active worktrees for a repo

917

- [ ] **D-16**: `muse similarity` — Show similarity score on PR detail page (head vs base)

918

- [ ] **D-17**: `muse emotion-diff` — Show emotional delta on PR detail page inline

919

920

### GROUP E — Seed Data

921

922

- [ ] **E-01**: Implement muse_objects / muse_snapshots / muse_commits / muse_tags seed data (all currently zero)

923

- [ ] **E-02**: Implement muse_variations / muse_phrases / muse_note_changes seed data (all currently zero)

924

- [ ] **E-03**: Create 12 artist/user profiles with bio, avatar, pinned repos (Bach, Chopin, Joplin, MacLeod, gabriel, sofia, marcus, yuki, aaliya, chen, fatou, pierre)

925

- [ ] **E-04**: Seed 12 repos across genres (well-tempered-clavier, nocturnes, maple-leaf-rag, etc.) with 50+ commits each

926

- [ ] **E-05**: Seed all muse_tags variants (emotion:*, stage:*, key:*, tempo:*, ref:*, genre:*)

927

- [ ] **E-06**: Seed milestones + milestone-linked issues for each repo (3-5 milestones per repo)

928

- [ ] **E-07**: Seed musehub_issue_comments (5+ per issue, with threading)

929

- [ ] **E-08**: Seed musehub_pr_comments (review comments with track/region/note targeting)

930

- [ ] **E-09**: Seed musehub_milestones + link to issues

931

- [ ] **E-10**: Seed musehub_webhooks + musehub_webhook_deliveries (success and failure cases)

932

- [ ] **E-11**: Seed musehub_render_jobs (pending, done, failed states)

933

- [ ] **E-12**: Seed musehub_events (push, PR, issue, release, star, fork, session events)

934

- [ ] **E-13**: Implement "Bach Remix War" narrative scenario (fork, PR, conflict, resolution)

935

- [ ] **E-14**: Implement "Chopin Meets Coltrane" narrative scenario (cross-genre 3-way merge)

936

- [ ] **E-15**: Implement "Ragtime EDM Collab" narrative scenario (multi-user session + release)

937

- [ ] **E-16**: Implement "Community Collab Chaos" narrative scenario (10 users, open PRs, debates)

938

- [ ] **E-17**: Implement "Goldberg Milestone" narrative scenario (milestone completion tracking)

939

- [ ] **E-18**: Seed CC MIDI content — download and embed real MIDI data from piano-midi.de for Bach/Chopin/Joplin pieces

940

- [ ] **E-19**: Seed full social graph — stars, watches, follows, forks, reactions (emojis including 🎵 🎹 🔥 👏)

941

- [ ] **E-20**: Seed notifications for all users (10-20 unread each, all types)

942

943

### GROUP F — Agent & Machine Readability

944

945

- [ ] **F-01**: All HTML pages must have `Accept: application/json` equivalent JSON endpoint — audit and add any missing

946

- [ ] **F-02**: Add `Link: rel=alternate type=application/json` headers on all UI pages

947

- [ ] **F-03**: oEmbed endpoint — return rich metadata (title, author, thumbnail URL, audio URL, duration, BPM, key)

948

- [ ] **F-04**: Open Graph + Twitter card meta tags on repo/commit/release/profile pages

949

- [ ] **F-05**: `GET /musehub/ui/{owner}/{repo}/analysis/{ref}` → machine-readable `analysis.json` schema at same path with `Accept: application/json`

950

- [ ] **F-06**: RSS/Atom feeds for: releases, commits, issues opened (per repo)

951

- [ ] **F-07**: `robots.txt` + `sitemap.xml` generation for public repos

952

- [ ] **F-08**: JSON-LD structured data (`schema.org/MusicComposition`) on repo landing pages

953

- [ ] **F-09**: Pagination via `Link: rel=next/prev` headers on all list endpoints (RFC 8288)

954

- [ ] **F-10**: Cursor-based pagination option alongside offset (better for agents with large datasets)

---

*Generated: 2026-03-01 | Version: 1.0 | Next review: after E-series issues are implemented*