new design docs

2025-11-03 20:50:57 -08:00
parent eb434dd08c
commit 2b1606443b
2 changed files with 1369 additions and 0 deletions
--- a/docs/contributor-workflow-analysis.md
+++ b/docs/contributor-workflow-analysis.md
@@ -0,0 +1,833 @@
+# Beads Contributor Workflow Analysis
+
+**Date**: 2025-11-03
+**Context**: Design discussion on how to handle beads issues in PR/OSS contribution workflows
+
+## The Problem (from #207)
+
+When contributing to OSS projects with beads installed:
+- Git hooks automatically commit contributor's personal planning to PRs
+- Contributor's experimental musings pollute the upstream project's issue tracker
+- No clear ownership/permission model for external contributors
+- Difficult to keep beads changes out of commits
+
+**Core tension**: Beads is great for team planning (shared namespace), but breaks down for OSS contributions (hierarchical gatekeeping).
+
+## Key Insights from Discussion
+
+### Beads as "Moving Frontier"
+
+Beads is not a traditional issue tracker. It captures the **active working set** - the sliding window of issues currently under attention:
+
+- Work moves fast with AI agents (10x-50x acceleration)
+- Completed work fades quickly (95% never revisited, should be pruned aggressively)
+- Future work is mostly blocked (small frontier of ready tasks)
+- The frontier is bounded by team size (dozens to hundreds of issues, not thousands)
+
+**Design principle**: Beads should focus on the "what's next" cloud, not long-term planning or historical archive.
+
+### The Git Ledger is Fundamental
+
+Beads achieves reliability despite being unreliable (merge conflicts, sync issues, data staleness) through:
+
+**A. Git is the ledger and immutable backstop for forensics**
+**B. AI is the ultimate arbiter and problem-solver when things go wrong**
+
+Any solution that removes the git ledger (e.g., gitignored contributor files) breaks this model entirely.
+
+### Requirements for Contributors
+
+Contributors need:
+- Git-backed persistence (multi-clone sync, forensics, AI repair)
+- Isolated planning space (don't pollute upstream)
+- Ability to propose selected issues upstream
+- Support for multiple workers across multiple clones of the same repo
+
+## Proposed Solutions
+
+### Idea 1: Fork-Aware Hooks + Two-File System
+
+**Structure**:
+```
+# Upstream repo
+.beads/
+  beads.jsonl          # Canonical frontier (committed)
+  .gitignore           # Ignores local.jsonl
+
+# Contributor's fork
+.beads/
+  beads.jsonl          # Synced from upstream (read-only)
+  local.jsonl          # Contributor planning (committed to fork)
+  beads.db             # Hydrated from both
+```
+
+**Detection**: Check for `upstream` remote to distinguish fork from canonical repo
+
+**Workflow**:
+```bash
+# In fork
+$ bd add "Experiment"        # → local.jsonl (committed to fork)
+$ bd sync                    # → Pulls upstream's beads.jsonl
+$ bd show                    # → Shows both
+$ bd propose bd-a3f8e9       # → Moves issue to beads.jsonl for PR
+```
+
+**Pros**:
+- Git ledger preserved (local.jsonl committed to fork)
+- Multi-clone sync works
+- Upstream .gitignore prevents pollution
+
+**Cons**:
+- Fork detection doesn't help teams using branches (most common workflow)
+- Two files to manage
+- Requires discipline to use `bd propose`
+
+### Idea 2: Ownership Metadata + Smart PR Filtering
+
+**Structure**:
+```jsonl
+{"id":"bd-123","owner":"upstream","title":"Canonical issue",...}
+{"id":"bd-456","owner":"stevey","title":"My planning",...}
+```
+
+**Workflow**:
+```bash
+$ bd add "Experiment"        # → Creates with owner="stevey"
+$ bd propose bd-456          # → Changes owner to "upstream"
+$ bd clean-pr                # → Filters commit to only upstream-owned issues
+$ git push                   # → PR contains only proposed issues
+```
+
+**Pros**:
+- Single file (simpler)
+- Works with any git workflow (branch, fork, etc)
+- Git ledger fully preserved
+
+**Cons**:
+- Requires discipline to run `bd clean-pr`
+- Clean commit is awkward (temporarily removing data)
+- Merge conflicts if upstream and contributor both modify beads.jsonl
+
+### Idea 3: Branch-Scoped Databases
+
+Track which issues belong to which branch, filter at PR time.
+
+**Implementation**: Similar to #2 but uses labels/metadata to track branch instead of owner.
+
+**Challenge**: Complex with multiple feature branches, requires tracking branch scope.
+
+### Idea 4: Separate Planning Repo (Most Isolated)
+
+**Structure**:
+```bash
+# Main project repos (many)
+~/projects/beads/.beads/beads.jsonl
+~/projects/foo/.beads/beads.jsonl
+
+# Single planning repo (one)
+~/.beads-planning/.beads/beads.jsonl
+
+# Configuration links them
+~/projects/beads/.beads/config.toml:
+  planning_repo = "~/.beads-planning"
+```
+
+**Workflow**:
+```bash
+$ cd ~/projects/beads
+$ bd add "My idea"           # → Commits to ~/.beads-planning/
+$ bd show                    # → Shows beads canonical + my planning
+$ bd propose bd-a3f8e9       # → Exports to beads repo for PR
+```
+
+**Pros**:
+- Complete isolation (separate git histories, zero PR pollution risk)
+- Git ledger fully preserved (both repos tracked)
+- Multi-clone works perfectly (clone both repos)
+- No special filtering/detection needed
+- **Scales better**: One planning repo for all projects
+
+**Cons**:
+- Two repos to manage
+- Less obvious for new users (where's my planning?)
+
+## Analysis: Fork vs Clone vs Branch
+
+**Clone**: Local copy of a repo (`git clone <url>`)
+- `origin` remote points to source
+- Push directly to origin (if you have write access)
+
+**Fork**: Server-side copy on GitHub
+- For contributors without write access
+- `origin` → your fork, `upstream` → original repo
+- Push to fork, then PR from fork → upstream
+
+**Branch**: Feature branches in same repo
+- Most common for teams with write access
+- Push to same repo, PR from branch → main
+
+**Key insight**: Branches are universal, forks are only for external contributors. Most teams work on branches in a shared repo.
+
+## Current Thinking: Idea 4 is Cleanest
+
+After analysis, **separate planning repo (#4)** is likely the best solution because:
+
+1. **Only solution that truly prevents PR pollution** (separate git histories)
+2. **Git ledger fully preserved** (both repos tracked)
+3. **Multi-clone works perfectly** (just clone both)
+4. **No complex filtering/detection needed** (simple config)
+5. **Better scaling**: One planning repo across all projects you contribute to
+
+The "managing two repos" concern is actually an advantage: your planning is centralized and project-agnostic.
+
+## Open Questions
+
+### About the Workflow
+
+1. **Where does PR pollution actually happen?**
+   - Scenario A: Feature branch → upstream/main includes all beads changes from that branch?
+   - Scenario B: Something else?
+
+2. **Multi-clone usage pattern**:
+   - Multiple clones on different machines?
+   - All push/pull to same remote?
+   - Workers coordinate via git sync?
+   - PRs created from feature branches?
+
+### About Implementation
+
+1. **Proposed issue IDs**: When moving issue from planning → canonical, keep same ID? (Hash-based IDs are globally unique)
+
+2. **Upstream acceptance sync**: If upstream accepts/modifies a proposal, how to sync back to contributor?
+   - `bd sync` detects accepted proposals
+   - Moves from planning repo to project's canonical beads.jsonl
+
+3. **Multiple projects**: One planning repo for all projects you contribute to, or one per project?
+
+4. **Backwards compatibility**: Single-user projects unchanged (single beads.jsonl)
+
+5. **Discovery**: How do users discover this feature? Auto-detect and prompt?
+
+## Next Steps
+
+Need to clarify:
+1. User's actual multi-clone workflow (understand the real use case)
+2. Where exactly PR pollution occurs (branch vs fork workflow)
+3. Which solution best fits the "git ledger + multi-clone" requirements
+4. Whether centralized planning repo (#4) or per-project isolation (#1/#2) is preferred
+
+## Design Principles to Preserve
+
+From the conversation, these are non-negotiable:
+
+- **Git as ledger**: Everything must be git-tracked for forensics and AI repair
+- **Moving frontier**: Focus on active work, aggressively prune completed work
+- **Multi-clone sync**: Workers across clones must coordinate via git
+- **Small databases**: Keep beads.jsonl small enough for agents to read (<25k)
+- **Simple defaults**: Don't break single-user workflows
+- **Explicit over implicit**: Clear boundaries between personal and canonical
+
+---
+
+# Decision: Separate Repos (Solution #4)
+
+**Date**: 2025-11-03 (continued discussion)
+
+## Why Separate Repos
+
+After consideration, **Solution #4 (Separate Planning Repos)** is the chosen approach:
+
+### Key Rationale
+
+1. **Beads as a Separate Channel**: Beads is fundamentally a separate communication channel that happens to use git/VCS for persistence, not a git-centric tool. It should work with any VCS (jujutsu, sapling, mercurial, etc.).
+
+2. **VCS-Agnostic Design**: Solution #1 (fork detection) is too git-centric and wouldn't work with other version control systems. Separate repos work regardless of VCS.
+
+3. **Maximum Flexibility**: Supports multiple workflows and personas:
+   - OSS contributor with personal planning
+   - Multi-phase development (different beads DBs for different stages)
+   - Multiple personas (architect, implementer, reviewer)
+   - Team vs personal planning separation
+
+4. **Zero PR Pollution Risk**: Completely separate git histories guarantee no accidental pollution of upstream projects.
+
+5. **Proven Pain Point**: Experience shows that accidental bulk commits (100k issues) can be catastrophic and traumatic to recover from. Complete isolation is worth the complexity.
+
+## Core Architecture Principles
+
+### 1. Multi-Repo Support (N ≥ 1)
+
+**Configuration should support N repos, including N=1 for backward compatibility:**
+
+When N=1 (default), this is the current single-repo workflow - no changes needed.
+When N≥2, multiple repos are hydrated together.
+
+```toml
+# .beads/config.toml
+
+# Default mode: single repo (backwards compatible)
+mode = "single"
+
+# Multi-repo mode
+[repos]
+  # Primary repo: where canonical issues live
+  primary = "."
+
+  # Additional repos to hydrate into the database
+  additional = [
+    "~/.beads-planning",           # Personal planning across all projects
+    "~/.beads-work/phase1",        # Architecting phase
+    "~/.beads-work/phase2",        # Implementation phase
+    "~/team-shared/.beads",        # Shared team planning
+  ]
+
+# Routing: where do new issues go?
+[routing]
+  mode = "auto"  # auto | explicit
+  default = "~/.beads-planning"    # Default for `bd add`
+
+  # Auto-detection: based on user permissions
+  [routing.auto]
+    maintainer = "."                   # If maintainer, use primary
+    contributor = "~/.beads-planning"  # Otherwise use planning repo
+```
+
+### 2. Hydration Model
+
+On `bd show`, `bd list`, etc., the database hydrates from multiple sources:
+
+```
+beads.db ← [
+  ./.beads/beads.jsonl           (primary, read-write if maintainer)
+  ~/.beads-planning/beads.jsonl   (personal, read-write)
+  ~/team-shared/.beads/beads.jsonl (shared, read-write if team member)
+]
+```
+
+**Metadata tracking**:
+```jsonl
+{
+  "id": "bd-a3f8e9",
+  "title": "Add dark mode",
+  "source_repo": "~/.beads-planning",  # Which repo owns this issue
+  "visibility": "local",               # local | proposed | canonical
+  ...
+}
+```
+
+### 3. Visibility States
+
+Issues can be in different states of visibility:
+
+- **local**: Personal planning, only in planning repo
+- **proposed**: Exported for upstream consideration (staged for PR)
+- **canonical**: In the primary repo (upstream accepted it)
+
+### 4. VCS-Agnostic Operations
+
+Beads should not assume git. Core operations:
+
+- **Sync**: `bd sync` should work with git, jj, hg, sl, etc.
+- **Ledger**: Each repo uses whatever VCS it's under (or none)
+- **Transport**: Issues move between repos via export/import, not git-specific operations
+
+## Workflow Examples
+
+### Use Case 1: OSS Contributor
+
+```bash
+# One-time setup
+$ mkdir ~/.beads-planning
+$ cd ~/.beads-planning
+$ git init && bd init
+
+# Contributing to upstream project
+$ cd ~/projects/some-oss-project
+$ bd config --add-repo ~/.beads-planning --routing contributor
+
+# Work
+$ bd add "Explore dark mode implementation"
+# → Goes to ~/.beads-planning/beads.jsonl
+# → Commits to planning repo (git tracked, forensic trail)
+
+$ bd show
+# → Shows upstream's canonical issues (read-only)
+# → Shows my planning issues (read-write)
+
+$ bd work bd-a3f8e9
+$ bd status bd-a3f8e9 in-progress
+
+# Ready to propose
+$ bd propose bd-a3f8e9 --target upstream
+# → Exports issue from planning repo
+# → Creates issue in ./beads/beads.jsonl (staged for PR)
+# → Marks as visibility="proposed" in planning repo
+
+$ git add .beads/beads.jsonl
+$ git commit -m "Propose: Add dark mode"
+$ git push origin feature-branch
+# → PR contains only the proposed issue, not all my planning
+```
+
+### Use Case 2: Multi-Phase Development
+
+```bash
+# Setup phases
+$ mkdir -p ~/.beads-work/{architecture,implementation,testing}
+$ for dir in ~/.beads-work/*; do (cd $dir && git init && bd init); done
+
+# Configure project
+$ cd ~/my-big-project
+$ bd config --add-repo ~/.beads-work/architecture
+$ bd config --add-repo ~/.beads-work/implementation
+$ bd config --add-repo ~/.beads-work/testing
+
+# Architecture phase
+$ bd add "Design authentication system" --repo ~/.beads-work/architecture
+$ bd show --repo ~/.beads-work/architecture
+# → Only architecture issues
+
+# Implementation phase (later)
+$ bd add "Implement JWT validation" --repo ~/.beads-work/implementation
+
+# View all phases
+$ bd show
+# → Shows all issues from all configured repos
+```
+
+### Use Case 3: Multiple Contributors on Same Project
+
+```bash
+# Team member Alice (maintainer)
+$ cd ~/project
+$ bd add "Fix bug in parser"
+# → Goes to ./beads/beads.jsonl (she's maintainer)
+# → Commits to project repo
+
+# Team member Bob (contributor)
+$ cd ~/project
+$ bd add "Explore performance optimization"
+# → Goes to ~/.beads-planning/beads.jsonl (he's contributor)
+# → Does NOT pollute project repo
+
+$ bd show
+# → Sees Alice's canonical issue
+# → Sees his own planning
+
+$ bd propose bd-xyz
+# → Proposes to Alice's canonical repo
+```
+
+## Implementation Outline
+
+### Phase 1: Core Multi-Repo Support
+
+**Commands**:
+```bash
+bd config --add-repo <path>         # Add a repo to hydration
+bd config --remove-repo <path>      # Remove a repo
+bd config --list-repos              # Show all configured repos
+bd config --routing <mode>          # Set routing: single|auto|explicit
+```
+
+**Config schema**:
+```toml
+[repos]
+primary = "."
+additional = ["path1", "path2", ...]
+
+[routing]
+default = "path"  # Where `bd add` goes by default
+mode = "auto"     # auto | explicit
+```
+
+**Database changes**:
+- Add `source_repo` field to issues
+- Hydration layer reads from multiple JSONLs
+- Writes go to correct JSONL based on source_repo
+
+### Phase 2: Proposal Flow
+
+**Commands**:
+```bash
+bd propose <issue-id> [--target <repo>]   # Move issue to target repo
+bd withdraw <issue-id>                    # Un-propose (move back)
+bd accept <issue-id>                      # Maintainer accepts proposal
+```
+
+**States**:
+- `visibility: local` → Personal planning
+- `visibility: proposed` → Staged for PR
+- `visibility: canonical` → Accepted by upstream
+
+### Phase 3: Routing Rules
+
+**Auto-detection**:
+- Detect if user is maintainer (git config, permissions)
+- Auto-route to primary vs planning repo
+
+**Config-based routing** (no new schema fields):
+```toml
+[routing]
+mode = "auto"  # auto | explicit
+default = "~/.beads-planning"  # Fallback for contributors
+
+# Auto-detection rules
+[routing.auto]
+maintainer = "."  # If user is maintainer, use primary repo
+contributor = "~/.beads-planning"  # Otherwise use planning repo
+```
+
+**Explicit routing** via CLI flag:
+```bash
+# Override auto-detection for specific issues
+bd add "Design system" --repo ~/.beads-work/architecture
+```
+
+**Discovered issue inheritance**:
+- Issues with parent_id automatically inherit parent's source_repo
+- Keeps related work co-located
+
+### Phase 4: VCS-Agnostic Sync
+
+**Sync operations**:
+- Detect VCS type per repo (git, jj, hg, sl)
+- Use appropriate sync commands
+- Fall back to manual sync if no VCS
+
+**Example**:
+```bash
+$ bd sync
+# Auto-detects:
+# - . is git → runs git pull
+# - ~/.beads-planning is jj → runs jj git fetch && jj rebase
+# - ~/other is hg → runs hg pull && hg update
+```
+
+## Migration Path
+
+### Existing Users (Single Repo)
+
+No changes required. Current workflow continues to work:
+
+```bash
+$ bd add "Task"
+# → .beads/beads.jsonl (as before)
+```
+
+### Opting Into Multi-Repo
+
+```bash
+# Create planning repo
+$ mkdir ~/.beads-planning && cd ~/.beads-planning
+$ git init && bd init
+
+# Link to project
+$ cd ~/my-project
+$ bd config --add-repo ~/.beads-planning
+$ bd config --routing auto  # Auto-detect maintainer vs contributor
+
+# Optionally migrate existing issues
+$ bd migrate --move-to ~/.beads-planning --filter "author=me"
+```
+
+### Teams Adopting Beads
+
+```bash
+# Maintainer sets up project
+$ cd ~/team-project
+$ bd init
+$ git add .beads/ && git commit -m "Initialize beads"
+
+# Contributors clone and configure
+$ git clone team-project
+$ cd team-project
+$ mkdir ~/.beads-planning && cd ~/.beads-planning
+$ git init && bd init
+$ cd ~/team-project
+$ bd config --add-repo ~/.beads-planning --routing contributor
+```
+
+## Design Decisions (Resolved)
+
+### 1. Namespace Collisions: **Option B (Global Uniqueness)**
+
+**Decision**: Use globally unique hash-based IDs that include timestamp + random component.
+
+**Rationale** (from VC feedback):
+- Option C (allow collisions) breaks dependency references: `bd dep add bd-a3f8e9 bd-b7c2d1` becomes ambiguous
+- Need to support cross-repo dependencies without repo-scoped namespacing
+- Hash should be: `hash(title + description + timestamp_ms + random_4bytes)`
+- Collision probability: ~1 in 10^12 (acceptable)
+
+### 2. Cross-Repo Dependencies: **Yes, Fully Supported**
+
+**Decision**: Dependencies work transparently across all repos.
+
+**Implementation**:
+- Hydrated database contains all issues from all repos
+- Dependencies stored by ID only (no repo qualifier needed)
+- `bd ready` checks dependency graph across all repos
+- Writes route back to correct JSONL via `source_repo` metadata
+
+### 3. Routing Mechanism: **Config-Based, No Schema Changes**
+
+**Decision**: Use config-based routing + explicit `--repo` flag. No new schema fields.
+
+**Rationale**:
+- `IssueType` already exists and is used semantically (bug, feature, task, epic, chore)
+- Labels are used semantically by VC (`discovered:blocker`, `no-auto-claim`)
+- Routing is a storage concern, not issue metadata
+- Simpler: auto-detect maintainer vs contributor from config
+- Discovered issues inherit parent's `source_repo` automatically
+
+### 4. Performance: **Smart Caching with File Mtime Tracking**
+
+**Decision**: SQLite DB is the cache, JSONLs are source of truth.
+
+**Implementation**:
+```go
+type MultiRepoStorage struct {
+    repos      []RepoConfig
+    db         *sql.DB
+    repoMtimes map[string]time.Time  // Track file modification times
+}
+
+func (s *MultiRepoStorage) GetReadyWork(ctx) ([]Issue, error) {
+    // Fast path: check if ANY JSONL changed
+    needSync := false
+    for repo, jsonlPath := range s.jsonlPaths() {
+        currentMtime := stat(jsonlPath).ModTime()
+        if currentMtime.After(s.repoMtimes[repo]) {
+            needSync = true
+            s.repoMtimes[repo] = currentMtime
+        }
+    }
+
+    // Only re-hydrate if something changed
+    if needSync {
+        s.rehydrate()  // Expensive but rare
+    }
+
+    // Query is fast (in-memory SQLite)
+    return s.db.Query("SELECT * FROM issues WHERE ...")
+}
+```
+
+**Rationale**: VC's polling loop (every 5-10 seconds) requires sub-second queries. File stat is microseconds, re-parsing only when needed.
+
+### 5. Visibility Field: **Optional, Backward Compatible**
+
+**Decision**: Add `visibility` as optional field, defaults to "canonical" if missing.
+
+**Schema**:
+```go
+type Issue struct {
+    // ... existing fields ...
+    Visibility *string `json:"visibility,omitempty"`  // nil = canonical
+}
+```
+
+**States**:
+- `local`: Personal planning only
+- `proposed`: Staged for upstream PR
+- `canonical`: Accepted by upstream (or default for existing issues)
+
+**Orthogonality**: Visibility and Status are independent:
+- `status: in_progress, visibility: local` → Working on personal planning
+- `status: open, visibility: proposed` → Proposed to upstream, awaiting review
+
+### 6. Library API Stability: **Transparent Hydration**
+
+**Decision**: Hybrid approach - transparent by default, explicit opt-in available.
+
+**Backward Compatible**:
+```go
+// Existing code keeps working - reads config.toml automatically
+store, err := beadsLib.NewSQLiteStorage(".beads/vc.db")
+```
+
+**Explicit Override**:
+```go
+// Library consumers can override config
+cfg := beadsLib.Config{
+    Primary: ".beads/vc.db",
+    Additional: []string{"~/.beads-planning"},
+}
+store, err := beadsLib.NewStorageWithConfig(cfg)
+```
+
+### 7. ACID Guarantees: **Per-Repo File Locking**
+
+**Decision**: Use file-based locks per JSONL, atomic within single repo.
+
+**Implementation**:
+```go
+func (s *Storage) UpdateIssue(issue Issue) error {
+    sourceRepo := issue.SourceRepo
+
+    // Lock that repo's JSONL
+    lock := flock(sourceRepo + "/beads.jsonl.lock")
+    defer lock.Unlock()
+
+    // Read-modify-write
+    issues := s.readJSONL(sourceRepo)
+    issues.Update(issue)
+    s.writeJSONL(sourceRepo, issues)
+
+    // Update in-memory DB
+    s.db.Update(issue)
+}
+```
+
+**Limitation**: Cross-repo transactions are NOT atomic (acceptable, rare use case).
+
+## Key Learnings from VC Feedback
+
+The VC project (VibeCoder) provided critical feedback as a real downstream consumer that uses beads as a library. Key insights:
+
+### 1. Two Consumer Models
+
+Beads has two distinct consumer types:
+- **CLI users**: Use `bd` commands directly
+- **Library consumers**: Use `beadsLib` in Go/TypeScript/etc. (like VC)
+
+Multi-repo must work transparently for both.
+
+### 2. Performance is Critical for Automation
+
+VC's executor polls `GetReadyWork()` every 5-10 seconds. Multi-repo hydration must:
+- Use smart caching (file mtime tracking)
+- Avoid re-parsing JSONLs on every query
+- Keep queries sub-second (ideally <100ms)
+
+### 3. Special Labels Must Work Across Repos
+
+VC uses semantic labels that must work regardless of repo:
+- `discovered:blocker` - Auto-generated blocker issues (priority boost)
+- `discovered:related` - Auto-generated related work
+- `no-auto-claim` - Prevent executor from claiming
+- `baseline-failure` - Self-healing baseline failures
+
+These are **semantic labels**, not routing labels. Don't overload labels for routing.
+
+### 4. Discovered Issues Routing
+
+When VC's analysis phase auto-creates issues with `discovered:blocker` label, they should:
+- Inherit parent's `source_repo` automatically
+- Stay co-located with related work
+- Not require manual routing decisions
+
+### 5. Library API Stability is Non-Negotiable
+
+VC's code uses `beadsLib.NewSQLiteStorage()`. Must not break. Solution:
+- Read `.beads/config.toml` automatically (transparent)
+- Provide `NewStorageWithConfig()` for explicit override
+- Hydration happens at storage layer, invisible to library consumers
+
+## Remaining Open Questions
+
+1. **Sync semantics**: When upstream accepts a proposed issue and modifies it, how to sync back?
+   - Option A: Mark as "accepted" in planning repo, keep both copies
+   - Option B: Delete from planning repo (it's now canonical)
+   - Option C: Keep in planning repo but mark as read-only mirror
+
+2. **Discovery**: How do users learn about this feature?
+   - Auto-prompt when detecting fork/contributor status?
+   - Docs + examples?
+   - `bd init --contributor` wizard?
+
+3. **Metadata fields**: Should `source_repo` be exposed in JSON export, or keep it internal to storage layer?
+
+4. **Proposed issue lifecycle**: What happens to proposed issues after PR is merged/rejected?
+   - Auto-delete from planning repo?
+   - Mark as "accepted" or "rejected"?
+   - Manual cleanup via `bd withdraw`?
+
+## Success Metrics
+
+How we'll know this works:
+
+1. **Zero pollution**: No contributor planning issues accidentally merged upstream
+2. **Multi-clone sync**: Workers on different machines see consistent state (via VCS sync)
+3. **Flexibility**: Users can configure for their workflow (personas, phases, etc.)
+4. **Backwards compat**: Existing single-repo users unaffected
+5. **VCS-agnostic**: Works with git, jj, hg, sl, or no VCS
+
+## Next Actions
+
+Suggested epics/issues to create (can be done in follow-up session):
+
+1. **Epic: Multi-repo hydration layer**
+   - Design schema for source_repo metadata
+   - Implement config parsing for repos.additional
+   - Build hydration logic (read from N JSONLs)
+   - Build write routing (write to correct JSONL)
+
+2. **Epic: Proposal workflow**
+   - Implement `bd propose` command
+   - Implement `bd withdraw` command
+   - Implement `bd accept` command (maintainer only)
+   - Design visibility state machine
+
+3. **Epic: Auto-routing**
+   - Detect maintainer vs contributor status
+   - Implement routing rules (label, priority, custom)
+   - Make `bd add` route to correct repo
+
+4. **Epic: VCS-agnostic sync**
+   - Detect VCS type per repo
+   - Implement sync adapters (git, jj, hg, sl)
+   - Handle mixed-VCS multi-repo configs
+
+5. **Epic: Migration and onboarding**
+   - Write migration guide
+   - Implement `bd migrate` command
+   - Create init wizards for common scenarios
+   - Update documentation
+
+---
+
+## Summary and Next Steps
+
+This document represents the design evolution for multi-repo support in beads, driven by:
+
+1. **Original problem** (GitHub #207): Contributors' personal planning pollutes upstream PRs
+2. **Core insight**: Beads is a separate communication channel that happens to use VCS
+3. **VC feedback**: Real-world library consumer with specific performance and API stability needs
+
+### Final Architecture
+
+**Solution #4 (Separate Repos)** with these refinements:
+
+- **N ≥ 1 repos**: Single repo (N=1) is default, multi-repo is opt-in
+- **VCS-agnostic**: Works with git, jj, hg, sapling, or no VCS
+- **Config-based routing**: No schema changes, auto-detect maintainer vs contributor
+- **Smart caching**: File mtime tracking, SQLite DB as cache layer
+- **Transparent hydration**: Library API remains stable, config-driven
+- **Global namespace**: Hash-based IDs with timestamp + random for uniqueness
+- **Cross-repo dependencies**: Fully supported, transparent to users
+- **Discovered issues**: Inherit parent's source_repo automatically
+
+### Why This Design Wins
+
+1. **Zero PR pollution**: Separate git histories = impossible to accidentally merge planning
+2. **Git ledger preserved**: All repos are VCS-tracked, full forensic capability
+3. **Maximum flexibility**: Supports OSS contributors, multi-phase dev, multi-persona workflows
+4. **Backward compatible**: Existing single-repo users unchanged
+5. **Performance**: Sub-second queries even with polling loops
+6. **Library-friendly**: Transparent to downstream consumers like VC
+
+### Related Documents
+
+- Original issue: GitHub #207
+- VC feedback: `./vc-feedback-on-multi-repo.md`
+- Implementation tracking: TBD (epics to be created)
+
+### Status
+
+**Design**: ✅ Complete (pending resolution of open questions)
+**Implementation**: ⏳ Not started
+**Target**: TBD
+
+Last updated: 2025-11-03
--- a/docs/vc-feedback-on-multi-repo.md
+++ b/docs/vc-feedback-on-multi-repo.md
@@ -0,0 +1,536 @@
+# VC Feedback on Multi-Repo Contributor Workflow
+
+**Date**: 2025-11-03
+**Context**: Response to `docs/contributor-workflow-analysis.md`
+**From**: VC Team (AI-supervised issue workflow system)
+
+## Executive Summary
+
+**Overall Assessment**: The multi-repo design is **sound and well-thought-out**. VC can adopt it post-bootstrap with minimal disruption.
+
+**Key Concerns**:
+1. **Library API stability** - Must remain transparent to library consumers
+2. **Cross-repo dependency resolution** - Critical for VC's blocker-first prioritization
+3. **Performance** - Hydration caching needed for VC's polling loop
+4. **Namespace collisions** - Recommend Option B (global uniqueness)
+
+**Current Status**: VC uses Beads v0.17.7 as a library, single-repo model, bootstrap phase (pre-contributors).
+
+---
+
+## 1. VC's Context & Usage Patterns
+
+### How VC Uses Beads
+
+**Architecture**:
+- Beads as library: `beadsLib.NewSQLiteStorage(".beads/vc.db")`
+- Extension model: VC adds tables (`vc_mission_state`, `vc_agent_events`)
+- Single repo: `.beads/vc.db` + `.beads/issues.jsonl`
+- Heavy use of ~20 library methods (GetIssue, CreateIssue, GetReadyWork, etc.)
+
+**Key Workflows**:
+1. **Blocker-first prioritization** - `GetReadyWork()` sorts by discovered:blocker label first
+2. **Atomic claiming** - `UPDATE issues SET status='in_progress' WHERE status='open'`
+3. **Auto-discovery** - AI analysis creates issues with `discovered:blocker` and `discovered:related` labels
+4. **Self-healing** - Enters "degraded mode" when `baseline-failure` issues exist
+5. **Executor exclusion** - `no-auto-claim` label prevents auto-claiming
+
+**Performance Profile**:
+- Polling loop: `GetReadyWork()` called every 5-10 seconds
+- Need sub-second response times
+- Cannot afford to re-read N JSONL files on every query
+
+---
+
+## 2. Impact Assessment
+
+### Short-Term (Bootstrap Phase): ✅ MINIMAL
+
+- Multi-repo is opt-in with backwards-compatible defaults
+- VC continues with single `.beads/vc.db` and `.beads/issues.jsonl`
+- No changes needed during bootstrap
+
+### Medium-Term (Post-Bootstrap): ⚠️ LOW-MEDIUM
+
+**Potential use cases**:
+- **Testing isolation**: Separate repo for experimental executor features
+- **Multi-contributor**: External contributors use `~/.beads-planning/`
+
+**Concerns**:
+- Cross-repo dependency resolution must work transparently
+- Atomic claiming must preserve ACID guarantees
+- Performance impact of multi-repo hydration
+
+### Long-Term (Self-Hosting): ✅ BENEFICIAL
+
+- Natural fit for VC's multi-contributor future
+- Prevents PR pollution from contributor planning
+- Aligns with VC's goal of becoming self-hosting
+
+---
+
+## 3. Critical Design Questions
+
+### Q1. Library API Stability ⚠️ CRITICAL
+
+**Question**: Is this a library API change or pure CLI feature?
+
+**Context**: VC uses `beadsLib.NewSQLiteStorage()` and expects single JSONL file.
+
+**What we need to know**:
+- Does `NewSQLiteStorage()` API change?
+- Is hydration transparent at library level?
+- Or is multi-repo purely a `bd` CLI feature?
+
+**Recommendation**:
+```go
+// Backwards-compatible: continue to work with no changes
+store, err := beadsLib.NewSQLiteStorage(".beads/vc.db")
+
+// Multi-repo should be configured externally (.beads/config.toml)
+// and hydrated transparently by the storage layer
+
+// If API must change, provide opt-in:
+cfg := beadsLib.Config{
+    Primary: ".beads/vc.db",
+    Additional: []string{"~/.beads-planning"},
+}
+store, err := beadsLib.NewStorageWithConfig(cfg)
+```
+
+---
+
+### Q2. Cross-Repo Dependencies ⚠️ CRITICAL
+
+**Question**: How does `GetReadyWork()` handle cross-repo dependencies?
+
+**Context**: VC's executor relies on dependency graph to find ready work.
+
+**Example scenario**:
+```
+canonical repo (.beads/vc.db):
+  vc-100 (open, P0) - ready work
+
+planning repo (~/.beads-planning):
+  vc-101 (open, P1, discovered:blocker) - ready work
+  vc-102 (open, P2) depends on vc-100  ← cross-repo dependency
+
+Expected results:
+  GetReadyWork() returns [vc-101, vc-100]  ← blocker-first, then priority
+                         (excludes vc-102 - blocked by vc-100)
+```
+
+**What we need**:
+- Hydration layer builds unified dependency graph across all repos
+- `GetReadyWork()` respects cross-repo dependencies
+- Performance acceptable for frequent polling
+
+**Recommendation**: Document cross-repo dependency behavior clearly and provide test cases.
+
+---
+
+### Q3. Atomic Operations Across Repos ⚠️ CRITICAL
+
+**Question**: Are writes atomic when multiple repos are hydrated?
+
+**Context**: VC's executor uses atomic claiming:
+```go
+// Must be atomic even if issue comes from planning repo
+UPDATE issues SET status = 'in_progress', executor_id = ?
+WHERE id = ? AND status = 'open'
+```
+
+**What we need to know**:
+- If multiple repos hydrate into single `.beads/vc.db`, are writes atomic?
+- How does hydration layer route writes back to correct JSONL?
+- Are there race conditions between multiple processes?
+
+**Recommendation**: Preserve ACID guarantees. Writes to hydrated database should be transparently routed to correct JSONL with transactional semantics.
+
+---
+
+### Q4. Visibility States vs Issue Status ⚠️ MEDIUM
+
+**Question**: Are visibility and status orthogonal?
+
+**Context**: VC uses `status: open | in_progress | closed` extensively.
+
+**From document**:
+```jsonl
+{
+  "status": "open",           // ← VC's current field
+  "visibility": "local",      // ← New field proposed
+  ...
+}
+```
+
+**What we need to know**:
+- Can an issue be `status: in_progress` and `visibility: local`?
+- Does `GetReadyWork()` filter by visibility?
+- Is this a breaking schema change?
+
+**Recommendation**: Clarify orthogonality and provide migration guide.
+
+---
+
+### Q5. Performance - Hydration on Every Query? ⚠️ CRITICAL
+
+**Question**: Does library-level hydration happen on every `GetReadyWork()` call?
+
+**Context**: VC's executor polls every 5-10 seconds.
+
+**Performance requirement**:
+```go
+// Executor polling loop
+for {
+    // Must be < 1 second, ideally < 100ms
+    readyWork, err := store.GetReadyWork(ctx, filter)
+    if len(readyWork) > 0 {
+        claimIssue(readyWork[0])
+    }
+    time.Sleep(5 * time.Second)
+}
+```
+
+**Recommendation**: Implement smart caching:
+```go
+type MultiRepoStorage struct {
+    repos []RepoConfig
+    cache *HydratedCache
+    lastSync map[string]time.Time
+}
+
+func (s *MultiRepoStorage) GetReadyWork(ctx context.Context) ([]Issue, error) {
+    // Check if any repo has changed since last sync
+    for _, repo := range s.repos {
+        if fileModTime(repo.JSONLPath) > s.lastSync[repo.Path] {
+            s.rehydrate(repo)  // ← Only re-read changed repos
+        }
+    }
+
+    // Query from cached hydrated database (fast)
+    return s.cache.GetReadyWork(ctx)
+}
+```
+
+**Rationale**: Cannot afford to re-parse N JSONL files every 5 seconds.
+
+---
+
+## 4. Design Feedback & Recommendations
+
+### F1. Namespace Collisions ✅ VOTE FOR OPTION B
+
+**From document's open question**:
+> 1. **Namespace collisions**: If two repos both have `bd-a3f8e9`, how to handle?
+>    - Option A: Hash includes repo path
+>    - Option B: Global uniqueness (hash includes timestamp + random)  ← **VC PREFERS THIS**
+>    - Option C: Allow collisions, use source_repo to disambiguate
+
+**Rationale**:
+- VC uses `vc-` prefix, Beads uses `bd-` prefix
+- Hash-based IDs should be globally unique
+- Avoids complexity of repo-scoped namespaces
+- Simpler for cross-repo dependencies
+- **Concern with Option C**: How does `bd dep add vc-123 vc-456` know which repo's `vc-123`?
+
+**Recommendation**: **Option B** (global uniqueness). Include timestamp + random in hash.
+
+---
+
+### F2. Routing Labels vs Semantic Labels ⚠️ IMPORTANT
+
+**From document**:
+```toml
+[routing.rules.label]
+label = "architecture"
+target = "~/.beads-work/architecture"
+```
+
+**Concern**: VC uses labels for semantic meaning, not routing:
+- `discovered:blocker` - auto-generated blocker issues
+- `discovered:related` - auto-generated related work
+- `no-auto-claim` - prevent executor from claiming
+- `baseline-failure` - self-healing baseline failures
+
+**Problem**: If Beads uses labels for routing, this conflicts with VC's semantic labels.
+
+**Recommendation**: Use separate mechanism for routing:
+```toml
+[routing.rules]
+  # Option 1: Use tags instead of labels
+  [[routing.rules.tag]]
+    tag = "architecture"
+    target = "~/.beads-work/architecture"
+
+  # Option 2: Use issue type
+  [[routing.rules.type]]
+    type = "design"
+    target = "~/.beads-work/architecture"
+
+  # Option 3: Use explicit category/phase field
+  [[routing.rules.phase]]
+    phase = "architecture"
+    target = "~/.beads-work/architecture"
+```
+
+**Rationale**: Don't overload labels - they're already a general-purpose tagging mechanism.
+
+---
+
+### F3. Proposal Workflow - Dependency Handling ⚠️ MEDIUM
+
+**Question**: What happens to dependencies when an issue moves repos?
+
+**Scenario**:
+```
+planning repo:
+  vc-100 "Explore feature"
+  vc-101 "Document findings"  (depends on vc-100)
+
+Proposal workflow:
+  bd propose vc-100  # ← Move to canonical
+
+Result:
+  canonical repo:
+    vc-100 "Explore feature"
+
+  planning repo:
+    vc-101 "Document findings"  (depends on vc-100)  ← Cross-repo dep now!
+```
+
+**Recommendation**: Document this behavior clearly:
+- Dependencies survive across repos (stored by ID)
+- `bd ready` checks cross-repo dependencies
+- Provide command: `bd dep tree --all-repos` to visualize
+- Consider warning when `bd propose` creates cross-repo deps
+
+---
+
+### F4. Discovered Issues Routing ⚠️ MEDIUM
+
+**Context**: VC's analysis phase auto-creates issues with labels:
+- `discovered:blocker`
+- `discovered:related`
+
+**Question**: Which repo do discovered issues go to?
+
+**Options**:
+1. **Same repo as parent issue** ← **VC PREFERS THIS**
+2. **Always canonical**
+3. **Configurable routing**
+
+**Rationale for Option 1**:
+- Discovered issues are part of work breakdown
+- Should stay with parent issue
+- Avoids fragmenting related work across repos
+
+**Example**:
+```
+planning repo:
+  vc-100 "Explore feature" (status: in_progress)
+
+Analysis phase discovers:
+  vc-101 "Fix edge case" (discovered:blocker, parent: vc-100)
+
+Expected: vc-101 goes to planning repo (same as vc-100)
+```
+
+---
+
+### F5. Self-Healing Across Repos ⚠️ LOW
+
+**Context**: VC has special behavior for `baseline-failure` label:
+- Enters "degraded mode"
+- Only works on baseline-failure issues until fixed
+
+**Question**: How does this interact with multi-repo?
+
+**Scenario**:
+```
+canonical repo:
+  vc-300 (baseline-failure) - tests failing
+
+planning repo:
+  vc-301 (baseline-failure) - build failing
+
+Expected: Executor sees both, enters degraded mode, works on either
+```
+
+**Recommendation**: Degraded mode should check ALL repos for baseline-failure labels.
+
+---
+
+## 5. Test Scenarios VC Needs to Work
+
+### Scenario 1: Cross-Repo Blocker-First Prioritization
+
+```
+canonical repo:
+  vc-100 (open, P0, no labels) - regular work
+
+planning repo:
+  vc-101 (open, P3, discovered:blocker) - blocker work
+
+Expected: GetReadyWork() returns [vc-101, vc-100]
+          (blocker-first, even though vc-101 is P3 in planning repo)
+```
+
+### Scenario 2: Cross-Repo Dependencies
+
+```
+canonical repo:
+  vc-200 (open, P0)
+
+planning repo:
+  vc-201 (open, P0) depends on vc-200
+
+Expected: GetReadyWork() returns [vc-200]
+          (vc-201 is blocked by vc-200)
+```
+
+### Scenario 3: Atomic Claiming
+
+```
+planning repo:
+  vc-300 (open, P0)
+
+Executor A: Claims vc-300
+Executor B: Tries to claim vc-300 concurrently
+
+Expected: Only one executor succeeds (ACID guarantee)
+          Write routes back to planning repo's JSONL
+```
+
+### Scenario 4: No-Auto-Claim Across Repos
+
+```
+canonical repo:
+  vc-400 (open, P0, no-auto-claim)
+
+planning repo:
+  vc-401 (open, P0, no-auto-claim)
+
+Expected: GetReadyWork() excludes both
+          (no-auto-claim works regardless of repo or visibility)
+```
+
+### Scenario 5: Baseline Failure Degraded Mode
+
+```
+canonical repo:
+  vc-500 (open, P0, baseline-failure)
+  vc-501 (open, P0) - regular work
+
+planning repo:
+  vc-502 (open, P0) - regular work
+
+Expected: Executor enters degraded mode
+          Only works on vc-500 (ignores vc-501 and vc-502)
+```
+
+---
+
+## 6. Documentation Requests
+
+### For Library Consumers (VC's Needs)
+
+1. **Migration guide**: How to adopt multi-repo for existing single-repo projects
+2. **API stability guarantees**: What will/won't break in future versions
+3. **Cross-repo dependency semantics**: Detailed behavior and examples
+4. **Performance characteristics**: Hydration cost, caching strategy, optimization tips
+5. **Schema changes**: Backward compatibility for visibility field
+
+### For Multi-Repo Users
+
+6. **Cross-repo workflow examples**: Contributor, multi-phase, multi-persona scenarios
+7. **Proposal workflow**: What happens to dependencies, labels, metadata when proposing
+8. **Troubleshooting**: Common issues (namespace collisions, sync conflicts, performance)
+9. **Best practices**: When to use multi-repo vs single-repo, repo organization patterns
+
+---
+
+## 7. Open Questions for Beads Team
+
+### Priority 1 - CRITICAL:
+1. Is this a breaking change to storage library API?
+2. How does cross-repo dependency resolution work at library level?
+3. What's the hydration performance model for frequent queries?
+4. Are atomic operations preserved across multi-repo?
+
+### Priority 2 - IMPORTANT:
+5. Which namespace collision strategy will you choose? (VC votes Option B)
+6. How will routing interact with semantic labels?
+7. What's the migration path for library consumers?
+
+### Priority 3 - NICE TO HAVE:
+8. How will discovered issues routing work?
+9. How will special labels (baseline-failure, no-auto-claim) work across repos?
+10. Will there be performance monitoring/profiling tools for multi-repo setups?
+
+---
+
+## 8. VC's Roadmap for Multi-Repo Adoption
+
+### Phase 1: Bootstrap (Current)
+- ✅ Stick with single repo (`.beads/vc.db`, `.beads/issues.jsonl`)
+- ✅ Monitor Beads releases for API changes
+- ✅ No code changes needed unless API breaks
+
+### Phase 2: Post-Bootstrap Testing
+- 📋 Evaluate multi-repo for isolated executor testing
+- 📋 Test cross-repo scenarios (dependencies, claiming, performance)
+- 📋 Validate blocker-first prioritization across repos
+
+### Phase 3: Self-Hosting with Contributors
+- 📋 Adopt multi-repo for contributor workflow
+- 📋 Contributors use `~/.beads-planning/`
+- 📋 Canonical issues stay in `.beads/issues.jsonl`
+- 📋 Executor handles both transparently
+
+---
+
+## 9. Summary & Recommendations
+
+### For Beads Team:
+
+**High Priority**:
+1. ✅ **Solution #4 (Separate Repos) is correct** - VCS-agnostic, clean isolation
+2. ⚠️ **Library API must remain stable** - Transparent hydration for existing consumers
+3. ⚠️ **Cross-repo dependencies are critical** - Must work transparently in GetReadyWork()
+4. ⚠️ **Performance matters** - Smart caching needed for polling loops
+5. ✅ **Choose Option B for namespaces** - Global uniqueness (timestamp + random)
+
+**Medium Priority**:
+6. ⚠️ **Don't overload labels for routing** - Use separate mechanism (tags/types/phases)
+7. ⚠️ **Document cross-repo dependency behavior** - Especially in proposal workflow
+8. ⚠️ **Provide migration guide** - For library consumers adopting multi-repo
+
+**Design is fundamentally sound**. VC can adopt post-bootstrap with minimal changes IF library API remains stable.
+
+### For VC Team:
+
+**Short-term**: No action needed. Continue single-repo development.
+
+**Medium-term**: Create tracking issues:
+- Monitor Beads multi-repo feature development
+- Evaluate adoption post-bootstrap
+- Test cross-repo scenarios with executor
+
+**Long-term**: Adopt for contributor workflow when self-hosting.
+
+---
+
+## 10. Contact & Follow-Up
+
+**VC Project**: https://github.com/steveyegge/vc
+**Current Beads Version**: v0.17.7
+**VC's Bootstrap Status**: Phase 1 (building core executor)
+
+**Questions for Beads team?** Feel free to ping VC maintainer or open an issue on VC repo for clarification.
+
+**Test scenarios needed?** VC can provide more detailed test cases for cross-repo scenarios.
+
+---
+
+**Thank you for the thorough design doc!** This is exactly the kind of forward-thinking design discussion that helps downstream consumers prepare for changes. 🙏