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.7 KiB

Raw Blame History

RFC 0003: Per Repo Blue Folders


Status	Implemented
Date	2026-01-24
Source Spike	per-repo-blue-folder

Summary

Currently all docs flow to one central .blue folder. Each repo should have its own .blue folder so docs live with code and git tracking works naturally.

Current Behavior

blue/                          # Central repo
├── .blue/
│   ├── repos/
│   │   ├── blue/docs/...      # Blue's docs
│   │   └── other-repo/docs/   # Other repo's docs (wrong!)
│   └── data/
│       └── blue/blue.db

All repos' docs end up in the blue repo's .blue/repos/.

Proposed Behavior

repo-a/
├── .blue/
│   ├── docs/
│   │   ├── rfcs/
│   │   ├── spikes/
│   │   └── runbooks/
│   └── blue.db
└── src/...

repo-b/
├── .blue/
│   ├── docs/...
│   └── blue.db
└── src/...

Each repo has its own .blue/ with its own docs and database.

Changes Required

1. Simplify BlueHome structure

pub struct BlueHome {
    pub root: PathBuf,      // Repo root
    pub blue_dir: PathBuf,  // .blue/
    pub docs_path: PathBuf, // .blue/docs/
    pub db_path: PathBuf,   // .blue/blue.db
}

2. Change detect_blue behavior

Find git repo root for current directory
Look for .blue/ there (don't search upward beyond repo)
Auto-create on first blue command (no blue init required)

Edge cases:

No git repo: Create .blue/ in current directory with warning
Monorepo: One .blue/ at git root (packages share it)
Subdirectory: Always resolve to git root

3. Flatten docs structure

Before: .blue/repos/<project>/docs/rfcs/ After: .blue/docs/rfcs/

No need for project subdirectory when per-repo.

4. Migration

Automatic on first run:

Detect old structure (.blue/repos/ exists)
Find docs for current project in .blue/repos/<project>/docs/
Move to .blue/docs/
Migrate database entries
Clean up empty directories
Log what was migrated

Conflict resolution: If docs exist in both locations, prefer newer by mtime.

Git Tracking

Repos should commit their .blue/ folder:

Track:

.blue/docs/** - RFCs, spikes, runbooks, etc.
.blue/blue.db - SQLite database (source of truth)
.blue/config.yaml - Configuration

Gitignore:

.blue/*.db-shm - SQLite shared memory (transient)
.blue/*.db-wal - SQLite write-ahead log (transient)

Recommended .gitignore addition:

# Blue transient files
.blue/*.db-shm
.blue/*.db-wal

Cross-Repo Coordination

The daemon/realm system (RFC 0001) handles cross-repo concerns:

Central daemon tracks active sessions
Realms coordinate contracts between repos
Each repo remains self-contained

FAQ

Q: Do I need to run blue init? A: No. Blue auto-creates .blue/ on first command.

Q: What about my existing docs in the central location? A: Auto-migrated on first run. Check git status to verify.

Q: Should I commit .blue/blue.db? A: Yes. It's the source of truth for your project's Blue state.

Q: What if I'm in a monorepo? A: One .blue/ at the git root. All packages share it.

Q: Can I use Blue without git? A: Yes, but with a warning. .blue/ created in current directory.

Q: How do I see cross-repo status? A: Use blue realm_status (requires daemon running).

Test Plan

New repo gets .blue/ on first blue command
Docs created in repo's own .blue/docs/
Database at .blue/blue.db
Old structure migrated automatically
Realm/daemon still works across repos
No git repo falls back gracefully with warning
Monorepo uses single .blue/ at root

"Right then. Let's get to it."

— Blue

3.7 KiB Raw Blame History