superviber/blue
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
blue/.blue/docs/spikes/2025-01-24T0300Z-worktree-naming-mismatch.done.md
Eric Garcia 0fea499957 feat: lifecycle suffixes for all document states + resolve all clippy warnings 
Every document filename now mirrors its lifecycle state with a status
suffix (e.g., .draft.md, .wip.md, .accepted.md). No more bare .md for
tracked document types. Also renamed all from_str methods to parse to
avoid FromStr trait confusion, introduced StagingDeploymentParams struct,
and fixed all 19 clippy warnings across the codebase.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 12:19:46 -05:00

3.4 KiB
Raw Blame History

Spike: Worktree Naming Mismatch Investigation

Date: 2025-01-24 Time-box: 30 minutes Status: Complete

Problem

User reported seeing:

Done. Implementation complete in worktree ../fungal-image-analysis-rfc0069
(branch rfc0069-job-status-namespace)

The worktree/branch weren't created with the right names.

Investigation

Blue's Actual Worktree Naming Patterns

Single-repo worktrees (crates/blue-mcp/src/handlers/worktree.rs):

  • Path: ~/.blue/worktrees/<stripped-name> (e.g., ~/.blue/worktrees/job-status-namespace)
  • Branch: <stripped-name> (RFC number prefix stripped per RFC 0007)
  • Example: RFC 0069-job-status-namespace → branch job-status-namespace

Realm multi-repo worktrees (crates/blue-mcp/src/handlers/realm.rs):

  • Path: ~/.blue/worktrees/<realm>/<rfc>/<repo>
  • Branch: rfc/<rfc> (prefixed with rfc/)
  • Example: RFC 0069-job-status-namespace → branch rfc/0069-job-status-namespace

What the User Saw

  • Path: ../fungal-image-analysis-rfc0069
  • Branch: rfc0069-job-status-namespace

Key Finding: Not From Blue

The observed output doesn't match either Blue pattern:

Aspect Blue Single-Repo Blue Realm User Saw
Path style Absolute (~/.blue/...) Absolute (~/.blue/...) Relative (../)
Path components worktrees/<name> worktrees/<realm>/<rfc>/<repo> <repo>-<rfc>
Branch format <stripped-name> rfc/<rfc> rfc<number>-<name> (no slash)

There's no code in Blue that:

  1. Produces relative paths like ../
  2. Uses the squashed rfc0069 format (no leading zeros, no separator)
  3. Combines repo name with RFC number in a single path segment

Root Cause

The message "Implementation complete in worktree" is not from Blue - it's from the LLM agent (Claude) that was implementing the feature.

The LLM agent likely:

  1. Constructed its own worktree path instead of using blue_worktree_create or blue_realm_worktree_create
  2. Used git worktree add directly via Bash, inventing its own naming convention
  3. Hallucinated the path/branch names in its completion message

Evidence

  1. Searched Blue codebase for ../ pattern - not found
  2. Searched for rfc\d+ squashed format - not found (only rfc3339 date formats)
  3. Blue's worktree success messages don't include "Implementation complete"
  4. Blue always uses absolute paths via state.home.worktrees_path or DaemonPaths

Additional Issues Found

While investigating, identified these potential problems in Blue's worktree code:

  1. Inconsistent naming between single/realm: Single-repo strips RFC number, realm preserves it with rfc/ prefix
  2. Store failures silently ignored: let _ = state.store.add_worktree() at worktree.rs:87
  3. Realm worktrees not persisted: realm.rs:551-691 never calls add_worktree()

Recommendations

  1. Guide LLM agents: Add clear instructions in blue_guide about always using Blue's worktree tools, never raw git worktree commands
  2. Validate in status: blue_status could check for orphan worktrees (git worktrees not in Blue's store)
  3. Consider RFC for guidance: Write an RFC for "LLM Agent Worktree Best Practices" if this recurs

Outcome

The worktree naming wasn't wrong in Blue - the LLM agent bypassed Blue's tools entirely and invented its own naming. The fix is behavioral (prompt engineering/guidance) rather than code.