blue/.blue/docs/dialogues/2026-01-26T0300Z-document-lifecycle-filenames-rfc-design.dialogue.recorded.md

Alignment Dialogue: Document Lifecycle Filenames Rfc Design

Draft: Dialogue 2031 Date: 2026-01-26 10:10 Status: In Progress Participants: 💙 Judge, 🧁 Muffin, 🧁 Cupcake, 🧁 Scone, 🧁 Eclair, 🧁 Donut, 🧁 Brioche, 🧁 Croissant, 🧁 Macaron, 🧁 Cannoli, 🧁 Strudel, 🧁 Beignet, 🧁 Churro RFC: document-lifecycle-filenames

Expert Panel

Agent	Role	Tier	Relevance	Emoji
💙 Judge	Orchestrator	—	—	💙
🧁 Muffin	UX Architect	Core	0.95	🧁
🧁 Cupcake	Technical Writer	Core	0.90	🧁
🧁 Scone	Systems Thinker	Core	0.85	🧁
🧁 Eclair	Domain Expert	Core	0.80	🧁
🧁 Donut	Devil's Advocate	Adjacent	0.70	🧁
🧁 Brioche	Integration Specialist	Adjacent	0.65	🧁
🧁 Croissant	Risk Analyst	Adjacent	0.60	🧁
🧁 Macaron	First Principles Reasoner	Adjacent	0.55	🧁
🧁 Cannoli	Pattern Recognizer	Adjacent	0.50	🧁
🧁 Strudel	Edge Case Hunter	Wildcard	0.40	🧁
🧁 Beignet	Systems Thinker	Wildcard	0.35	🧁
🧁 Churro	Domain Expert	Wildcard	0.30	🧁

Alignment Scoreboard

Agent	Wisdom	Consistency	Truth	Relationships	Total
🧁 Muffin	4	4	4	4	16
🧁 Cupcake	3	4	4	3	14
🧁 Scone	5	4	5	4	18
🧁 Eclair	4	5	5	4	18
🧁 Donut	4	3	4	3	14
🧁 Brioche	4	4	4	4	16
🧁 Croissant	4	4	5	3	16
🧁 Macaron	5	3	5	3	16
🧁 Cannoli	4	4	4	3	15
🧁 Strudel	4	4	5	3	16
🧁 Beignet	4	4	4	4	16
🧁 Churro	3	4	4	3	14

Initial ALIGNMENT: 189 / 240 (79%)

Perspectives Inventory

ID	Agent	Perspective	Round
P01	Muffin	.done-rfc creates invisible coupling between spike and RFC doc types	R1
P02	Muffin	Cross-reference updates missing from implementation plan	R1
P03	Cupcake	No glossary/onboarding for 10 status abbreviations	R1
P04	Cupcake	.done-rfc contradicts code at spike.rs:95-109	R1
P05	Scone	Filenames shift from immutable identifiers to mutable state	R1
P06	Scone	Rename cascade lacks rollback semantics	R1
P07	Scone	Default-state omission creates asymmetry	R1
P08	Eclair	.done-rfc unreachable — handler blocks completion	R1
P09	Eclair	Default omission hides active work	R1
P10	Donut	Cross-reference breakage underestimated (IDE, PRs, static sites)	R1
P11	Donut	Option C (subdirectories) solves both problems	R1
P12	Brioche	Need centralized status transition hook for atomicity	R1
P13	Croissant	Silent overwrite at HHMM granularity is data loss vector	R1
P14	Macaron	Filenames exist to locate, not to store state	R1
P15	Macaron	Default omission creates cross-type ambiguity	R1
P16	Cannoli	Filesystem-git impedance mismatch	R1
P17	Strudel	.done-rfc conflates two state transitions	R1
P18	Strudel	Abandoned spikes invisible (no suffix forever)	R1
P19	Beignet	3-way transaction (SQLite + file + git) without rollback	R1
P20	Churro	git blame discontinuity destroys provenance	R1

Tensions Tracker

ID	Tension	Status	Raised	Resolved
T1	.done-rfc suffix is unreachable: spike.rs:95-109 blocks completion for recommends-implementation	Open	R1 (12/12)	—
T2	Default-state suffix omission creates ambiguity across doc types	Open	R1 (10/12)	—
T3	Rename cascade is a 3-way transaction (SQLite + file + git) with no rollback semantics	Open	R1 (8/12)	—

Round 1: Opening Arguments

Muffin 🧁

The .done-rfc suffix creates invisible coupling between spike and RFC document types — understanding the filename requires knowing the spike-to-RFC relationship. More critically, spike.rs:95-109 blocks completion when outcome is recommends-implementation, returning rfc_required instead of success. The suffix assumes both steps completed, but the code prevents it.

Cross-reference updates are missing from the implementation plan. The RFC says "most survive" via title-based lookups, but provides no evidence this holds across all 9 document types. rename_for_status() updates SQLite file_path but says nothing about markdown link updates.

Cupcake 🧁

Nine document types with 10 abbreviations (.wip, .impl, .super, .done-rfc) and no onboarding path: no glossary file, no autocomplete hints in MCP tool descriptions, no migration guide. A new contributor sees cryptic suffixes and reaches for the wrong status.

The .done-rfc suffix contradicts code behavior. spike.rs:95-109 refuses to complete spikes with recommends-implementation outcome. Either the code needs changing or the RFC must acknowledge .done-rfc is a manual rename, not a tool-generated state.

Scone 🧁

The RFC fundamentally changes the semantic contract of filenames. Currently filenames are immutable identifiers (git history, bookmarks, cross-references). Status-in-filename transforms them into mutable representations of document state. If someone manually renames slug.done.md back to slug.md, the filename contradicts SQLite. Two conflicting sources of truth.

The rename cascade lacks rollback: What happens when git mv fails (file open, permissions, dirty tree)? What about store update succeeding but rename failing? The spike notes "manageable" but specifies no error recovery paths.

Default-state omission is elegant but asymmetric: .impl proves implementation, but no suffix could mean "draft" or "just old convention." Always-use-suffixes for stateful docs would be more honest.

Eclair 🧁

No code path sets a spike to complete with recommends-implementation outcome. The handler either completes (for no-action/decision-made) or blocks (for recommends-implementation). The .done-rfc suffix assumes both can happen.

Default-state omission hides active work. A directory of 15 2026-01-26T0856Z-*.md files could be active investigations or stale drafts. Would .wip for in-progress spikes be more honest than pretending the default is self-evident?

Donut 🧁

Cross-reference breakage is underestimated. IDE jump-to-definition, git PR review links, documentation websites, shell scripts — all break on rename. "Accept that external bookmarks break" reveals the cost: every status transition becomes a coordination event.

Option C (subdirectories) solves both problems: clean URLs that don't break, and ls rfcs/implemented/ gives you exactly what you want. The RFC dismisses this as "complex for tools," but adding git mv + store updates + reference scanning is equally complex — just distributed.

Status suffix scatter violates temporal coherence. Three statuses of RFC 0031 interleave with other RFCs when sorted.

Brioche 🧁

Every status change handler across 9 document types must coordinate three atomic operations: SQLite update, markdown rewrite, filesystem rename. The RFC shows a rename_for_status helper but doesn't specify who calls it or when. We need a centralized status transition hook that guarantees all three happen atomically.

The .done-rfc suffix is ambiguous under current handler logic — completion is blocked until RFC exists. The rebuild_filename() transition detection from no-suffix to suffix state needs careful attention.

Croissant 🧁

Rename cascades break atomic consistency. Cross-document references are filename-based in markdown, not title-based as the RFC claims. The "future work" cross-reference updater isn't optional — it's foundational.

The .done-rfc suffix conflicts with the status model at spike.rs:95-109. Silent overwrite risk at HHMM granularity is load-bearing, not cosmetic — a productive hour creates 60 one-minute collision windows. Status suffixes make this worse (more renames = more collision windows).

Macaron 🧁

From first principles: filenames exist to help humans locate files, not to store structured data. We have SQLite for state, git for history, frontmatter for metadata. Kubernetes, NPM, and git all keep status in metadata, not names. The rename-on-status pattern fights the filesystem's core assumption: stable identifiers.

Default-state omission creates parsing ambiguity: 2026-01-26T0856Z-slug.md could be an in-progress spike, a recorded decision, an open postmortem, or an in-progress audit. The filesystem browser loses the self-documenting property the RFC promises.

Cannoli 🧁

The proposal treats filenames as data carriers, encoding both temporal metadata and state. This creates a filesystem-git impedance mismatch — Git treats filenames as immutable identifiers, while this RFC makes them mutable.

Default-state omission: 0031-slug.md could be a draft RFC or a legacy file without suffix. No migration signal distinguishes "intentionally draft" from "created before this RFC."

Strudel 🧁

The .done-rfc suffix conflates two state transitions: spike completion and RFC creation. spike.rs:95-109 deliberately prevents completion until RFC exists — when does the rename happen? Before RFC creation contradicts handler logic; after it, who triggers it?

Abandoned spikes stay "in-progress" forever with no suffix. The timestamp helps identify age, but there's no status signal for "stale." Default noise means active and stale look identical.

Beignet 🧁

Every status change now triggers filesystem mutation + SQLite update + git operation in lockstep. Current handlers only touch SQLite + frontmatter. Adding git mv introduces failure modes where three systems desynchronize. Once filenames encode status, human workflows will depend on that encoding. Breaking the contract via desync is worse than never having the feature.

Default-state filename ambiguity: 0042-slug.md without suffix could be draft RFC, accepted ADR, or recorded Decision. Three different document types look identical in their default states.

Churro 🧁

When an RFC transitions from 0031-slug.md to 0031-slug.impl.md, every blame annotation shows "last modified when renamed" instead of the actual substantive change. For long-lived design documents, this destroys provenance tracking.

The .done-rfc suffix is unreachable under current handler logic at spike.rs:95-109. Active work is invisible with no-suffix defaults — you can't tell draft from accepted without opening files.

---

💙 Judge — Round 1 Summary

Strong consensus on 3 tensions:

1. T1 (12/12): .done-rfc is unreachable. spike.rs:95-109 blocks completion for recommends-implementation. The suffix cannot be generated by the current tool flow.

2. T2 (10/12): Default-state omission creates cross-type ambiguity. No suffix means different things for different doc types, and can't distinguish "intentionally default" from "pre-RFC legacy."

3. T3 (8/12): Rename cascade introduces a 3-way distributed transaction (SQLite + filesystem + git) with no rollback semantics. Cross-references ARE filename-based in markdown.

Notable minority positions:

• Donut advocates Option C (subdirectories) as superior to suffix approach
• Macaron challenges the premise: filenames should locate, not store state
• Croissant flags HHMM overwrite risk as load-bearing

Round 2 directive: All experts must propose concrete resolutions for T1, T2, and T3. Converge on amended RFC language.

Round 2: Tension Resolution

Muffin 🧁

T1 resolution: Drop .done-rfc. When spike_complete with recommends-implementation triggers RFC creation, the spike gets .done suffix afterward (via a second spike_complete call with decision-made outcome, or by having rfc_create auto-complete the source spike). The RFC-spike linkage lives in SQLite source_spike field, not the filename. One status per filename.

T2 resolution: Accept the trade-off. Default-state omission is the right call because the majority browsing use case is "which of these are done?" The presence of a suffix signals completion, its absence signals "still active or new." This is like how we read email: unread is default, stars/labels are additive. Document type is already disambiguated by directory (rfcs/, spikes/, etc.).

T3 resolution: Use fs::rename + store.update_file_path as a two-step best-effort operation. If rename succeeds but store update fails, the file has the right name and the store catches up on next scan. If rename fails, the store hasn't changed either — no inconsistency. Skip git mv — let the user commit normally. git add -A captures renames automatically. No need for explicit git mv.

Cupcake 🧁

T1 resolution: Replace .done-rfc with .done for all completed spikes regardless of outcome. Record outcome in frontmatter and SQLite only. Add a ## Outcome section to spike markdown that says "Recommends: RFC 0031" with a link. The filename signals done-ness; the content signals what happened.

T2 resolution: Add a sentence to the RFC: "Files without status suffixes are in their initial state. Legacy files without suffixes created before this RFC are also treated as initial state. This is intentional — no migration required." Explicit documentation removes the ambiguity.

T3 resolution: The rename operation should be filesystem-first, store-second. If fs::rename fails, return an error and don't touch the store. If the store update fails after a successful rename, log a warning — the next blue_sync can reconcile file paths by scanning the filesystem. This makes the filesystem the source of truth for paths, which it already is.

Scone 🧁

T1 resolution: Agree — drop .done-rfc. Spike outcomes belong in the document body and SQLite metadata, not filenames. A spike is either in-progress or done. Binary. The filename vocabulary becomes: no suffix = active, .done = complete. Clean.

T2 resolution: I retract my always-use-suffixes suggestion. After reflection, the directory structure already disambiguates type (rfcs/ vs spikes/ vs adrs/). Within a single directory, "no suffix = initial state" is unambiguous because all files in rfcs/ are RFCs. The ambiguity I raised only exists if you mix document types in one directory, which Blue doesn't do.

T3 resolution: The rename transaction should be: (1) rename file, (2) update store, (3) NO git operation. Let the user or CI handle git staging. The rename_for_status function should return a RenameResult with the old and new paths so callers can log it. If step 1 fails, abort. If step 2 fails after step 1 succeeds, the filesystem is authoritative — store reconciliation on next load.

Eclair 🧁

T1 resolution: Drop .done-rfc entirely. Modify spike_complete handler: when rfc_create is called with source_spike, have it auto-complete the source spike with decision-made outcome after RFC creation succeeds. This closes the spike → RFC loop without needing a special suffix. The filename just gets .done.

T2 resolution: Accept default-state omission. The user's goal was "see at a glance which are done." Suffixes answer "what's finished?" not "what's the exact status?" The absence of a suffix = "not yet done" is the right mental model. If you need the exact status, open the file or query the store.

T3 resolution: Two-phase, filesystem-first. Drop git mv from the RFC entirely — it's unnecessary overhead. git detects renames automatically when content similarity exceeds 50%. Since we only change the filename (not content), git diff --find-renames will always detect it. The RFC should specify: fs::rename then store.update_file_path. No git integration needed.

Donut 🧁

T1 resolution: I concede .done-rfc should go. The experts are right that it's unreachable. Use .done for all completed spikes. Store the outcome in metadata.

T2 resolution: I still think this is a real problem, but I accept the panel's argument that directory-per-type disambiguates. Within rfcs/, no suffix means draft. Within spikes/, no suffix means in-progress.

T3 resolution: I withdraw my Option C advocacy for this RFC. The panel has converged on suffix approach. But the RFC should explicitly add to the test plan: "Integration: Verify fs::rename failure leaves store unchanged" and "Integration: Verify store update failure after rename is recoverable via filesystem scan."

Brioche 🧁

T1 resolution: Drop .done-rfc. Remove it from the vocabulary table and status_suffix() match. All completed spikes get .done regardless of outcome. Outcome lives in frontmatter ## Outcome section and SQLite outcome field.

T2 resolution: Accept omission. Add to RFC: "Within each document type's directory, absence of a status suffix unambiguously means the initial/default state for that type."

T3 resolution: Centralized transition_status() function in blue-core that: (1) renames file, (2) updates store file_path, (3) updates markdown frontmatter status. All three in sequence, filesystem-first. No git operation. The function returns Result<TransitionResult, TransitionError> with enough info for callers to handle partial failure. Add this to the Code Changes section.

Croissant 🧁

T1 resolution: Agree — drop .done-rfc. It was a nice idea but unreachable and unnecessary. Store outcome metadata, not filename metadata.

T2 resolution: Accept. Directory-per-type makes it clear.

T3 resolution: The RFC should specify error handling explicitly:

1. fs::rename(old, new) — if fails, return error, done
2. store.update_file_path() — if fails, attempt fs::rename(new, old) rollback
3. update_markdown_status() — if fails, log warning (non-critical)

This gives us a best-effort rollback for the critical path (file + store) and accepts that frontmatter is eventually consistent. Move overwrite protection from "Future Work" to the main design — it's a prerequisite for status suffixes.

Macaron 🧁

T1 resolution: Drop .done-rfc. Status suffixes should map 1:1 to the status field in SQLite. No compound statuses, no outcome encoding. Clean separation.

T2 resolution: I maintain that default omission is philosophically wrong (filenames shouldn't store state at all), but I accept the panel's pragmatic resolution. Directory-per-type disambiguates within Blue's structure.

T3 resolution: I accept the filesystem-first, no-git approach. But add a design principle to the RFC: "Filenames are derived views of store state. The SQLite store is authoritative. If filename and store disagree, store wins. blue_sync reconciles."

Cannoli 🧁

T1 resolution: Drop .done-rfc. Unanimous.

T2 resolution: Accept omission with documentation.

T3 resolution: Agree with Croissant's error handling sequence. Add rollback on store failure.

Strudel 🧁

T1 resolution: Drop .done-rfc. Consider having rfc_create with source_spike parameter auto-complete the source spike — this closes the workflow gap that .done-rfc was trying to address.

T2 resolution: Accept. But add to test plan: "Verify that legacy files (pre-RFC) without suffixes are correctly treated as default state."

T3 resolution: Agree with filesystem-first, no-git. Add the rollback attempt on store failure. Also: the overwrite protection (checking file existence before write) should be a prerequisite, not future work.

Beignet 🧁

T1 resolution: Drop .done-rfc. The panel is unanimous.

T2 resolution: Accept with documentation.

T3 resolution: Filesystem-first, store-second, no git. Add explicit rollback. The RFC should add to Design: "Atomicity: If filesystem rename succeeds but store update fails, attempt rollback rename. If rollback also fails, log error with both paths for manual resolution."

Churro 🧁

T1 resolution: Drop .done-rfc. Use .done for all completed spikes.

T2 resolution: Accept. Directory context disambiguates.

T3 resolution: Agree with the panel. Filesystem-first, rollback on store failure, no git operations. This keeps the implementation simple and the failure modes bounded.

---

💙 Judge — Round 2 Summary

All 3 tensions resolved:

T1 RESOLVED (12/12): Drop .done-rfc from vocabulary. All completed spikes get .done regardless of outcome. Spike outcome lives in frontmatter and SQLite. Consider having rfc_create with source_spike auto-complete the source spike.

T2 RESOLVED (12/12): Accept default-state omission. Directory-per-type disambiguates. Add explicit documentation: "Within each document type directory, absence of suffix means initial state. Legacy files without suffixes are treated identically."

T3 RESOLVED (12/12): Filesystem-first, store-second, no git operations. Error handling:

1. fs::rename(old, new) — if fails, return error
2. store.update_file_path() — if fails, attempt fs::rename(new, old) rollback
3. update_markdown_status() — if fails, log warning Move overwrite protection from Future Work to Design.

Consensus amendments to RFC 0031:

1. Remove .done-rfc from vocabulary table, filename examples, status_suffix() match, and test plan
2. Add "Design Principle: SQLite store is authoritative. Filenames are derived views."
3. Add error handling sequence with rollback to rename_for_status()
4. Move overwrite protection from Future Work to Design
5. Drop git mv requirement — git detects renames automatically
6. Add documentation note about default-state omission and legacy files
7. Confirm dialogue files use new YYYY-MM-DDTHHMMZ prefix (already in RFC, user confirmed)

Round 3: Convergence Check

Muffin 🧁

Aligned. The amendments address all my concerns. Drop .done-rfc, filesystem-first rename, no git operations. The RFC is stronger for it.

Cupcake 🧁

Aligned. Documentation note about default states resolves the onboarding concern. The glossary lives in the RFC itself (vocabulary table), which is sufficient.

Scone 🧁

Aligned. I retracted my always-use-suffixes position in Round 1. The filesystem-first approach with rollback is sound. Store-as-authority is the right principle.

Eclair 🧁

Aligned. The auto-complete-on-RFC-create suggestion handles the spike→RFC workflow cleanly. All tensions resolved.

Donut 🧁

Aligned. I withdrew Option C advocacy. The suffix approach with the amendments is workable. The test plan additions matter.

Brioche 🧁

Aligned. Centralized transition_status() with filesystem-first semantics covers the atomicity concern.

Croissant 🧁

Aligned. Error handling with rollback addresses my risk concerns. Overwrite protection as prerequisite, not future work.

Macaron 🧁

Aligned. I still believe filenames shouldn't store state in principle, but the "derived view" framing makes the design defensible. Store is authoritative.

Cannoli 🧁

Aligned.

Strudel 🧁

Aligned. Legacy file handling in test plan addresses my edge case.

Beignet 🧁

Aligned. The 3-way transaction concern is resolved by removing git from the equation.

Churro 🧁

Aligned.

---

💙 Judge — Round 3 Summary

12/12 ALIGNED. Dialogue converged.

Final Alignment Scoreboard

Agent	Wisdom	Consistency	Truth	Relationships	Total
🧁 Muffin	5	5	5	5	20
🧁 Cupcake	5	5	5	5	20
🧁 Scone	5	5	5	5	20
🧁 Eclair	5	5	5	5	20
🧁 Donut	5	5	5	5	20
🧁 Brioche	5	5	5	5	20
🧁 Croissant	5	5	5	5	20
🧁 Macaron	5	5	5	5	20
🧁 Cannoli	5	5	5	5	20
🧁 Strudel	5	5	5	5	20
🧁 Beignet	5	5	5	5	20
🧁 Churro	5	5	5	5	20

Total ALIGNMENT: 240 / 240 (100%)

Converged Amendments

The following changes must be applied to RFC 0031:

1. Drop .done-rfc: Remove from vocabulary table (line 141), filename examples (lines 97, 267), status_suffix() match, and test plan (line 280). All completed spikes use .done.

2. Add design principle: "The SQLite store is the authoritative source of document status. Filenames are derived views. If filename and store disagree, the store wins. blue_sync reconciles."

3. Error handling for rename_for_status():

   fn rename_for_status(...) -> Result<(), Error> {
       // 1. fs::rename — if fails, return error
       // 2. store.update_file_path — if fails, attempt rollback rename
       // 3. update_markdown_status — if fails, log warning (non-critical)
   }
   

4. Drop git mv: Remove from mitigations. Git detects renames automatically via content similarity.

5. Move overwrite protection: From Future Work to Design section. File existence check before write is a prerequisite for status suffixes.

6. Add legacy file note: "Files without status suffixes are in their initial state. Legacy files created before this RFC are treated identically — no migration required."

7. Confirm dialogue timestamp: dialogue.rs uses new YYYY-MM-DDTHHMMZ format (already in scope).