0fea499957
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>
155 lines
3.7 KiB
Markdown
155 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```rust
|
|
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:
|
|
|
|
1. Detect old structure (`.blue/repos/` exists)
|
|
2. Find docs for current project in `.blue/repos/<project>/docs/`
|
|
3. Move to `.blue/docs/`
|
|
4. Migrate database entries
|
|
5. Clean up empty directories
|
|
6. 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
|