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

5.7 KiB

Raw Blame History

Spike: Document Lifecycle Filenames


Status	Complete
Date	2026-01-26
Time Box	30 minutes

Question

How should Blue encode document lifecycle status in filenames so that browsing a directory reveals document state at a glance? What format works across all 9 document types, preserves lexicographic sorting, remains filesystem-safe, and integrates with the ISO 8601 timestamp work from RFC 0030?

Investigation

Current State

9 document types. Status stored in SQLite + markdown frontmatter. Zero status information in filenames.

Type	Filename Pattern	Statuses	Browse Problem
RFC	`0030-slug.md`	draft, accepted, in-progress, implemented, superseded	Can't tell if draft or shipped
Spike	`2026-01-26-slug.md`	in-progress, complete (+outcome)	Can't tell if resolved
ADR	`0004-slug.md`	accepted, in-progress, implemented	Can't tell if active
Decision	`2026-01-26-slug.md`	recorded	Always same (no problem)
PRD	`0001-slug.md`	draft, approved, implemented	Can't tell if approved
Postmortem	`2026-01-26-slug.md`	open, closed	Can't tell if resolved
Runbook	`slug.md`	active, archived	Can't tell if current
Dialogue	`2026-01-26-slug.dialogue.md`	draft, published	Can't tell if final
Audit	`2026-01-26-slug.md`	in-progress, complete	Can't tell if done

Key Constraint: No Code Parses Filenames

From RFC 0030 investigation: store.rs:2232 regex only extracts numbered doc prefixes. Document lookups use SQLite by title. Renaming files does not break internal lookups — only file_path in the documents table needs updating.

Design Options

Option A: Status suffix before `.md`

0030-iso-8601-timestamps.draft.md     → 0030-iso-8601-timestamps.impl.md
2026-01-26T0856Z-kanban-apps.wip.md   → 2026-01-26T0856Z-kanban-apps.done.md

Pros: Clear at a glance, sorts by number/date first, status is visual suffix Cons: Renaming on status change breaks git history, external links

Option B: Status prefix after number/date

0030-DRAFT-iso-8601-timestamps.md     → 0030-IMPL-iso-8601-timestamps.md
2026-01-26T0856Z-WIP-kanban-apps.md   → 2026-01-26T0856Z-DONE-kanban-apps.md

Pros: Status visible early in filename Cons: Disrupts slug, ALL_CAPS is noisy, breaks cross-references

Option C: Status subdirectories

rfcs/draft/0030-iso-8601-timestamps.md    → rfcs/implemented/0030-iso-8601-timestamps.md
spikes/active/2026-01-26T0856Z-kanban.md  → spikes/complete/2026-01-26T0856Z-kanban.md

Pros: Clean filenames, easy browsing by status, familiar (like git branches) Cons: Moving files between directories, deeper path nesting, complex for tools

Option D: Status dot-notation (minimal)

0030-iso-8601-timestamps.d.md  → 0030-iso-8601-timestamps.i.md

Pros: Minimal visual noise Cons: Single letter is cryptic, easy to miss

Option E: Combination — timestamp + status suffix

2026-01-26T0856Z-kanban-apps.spike.wip.md
2026-01-26T0856Z-kanban-apps.spike.done-rfc.md
0030-iso-8601-timestamps.rfc.draft.md
0030-iso-8601-timestamps.rfc.impl.md

Pros: Self-documenting (type + status), works across all doc types Cons: Long filenames, multiple dots

The Rename Problem

All status-in-filename approaches require renaming files when status changes. This has consequences:

Git history: git log --follow tracks renames, but git blame shows only current name
Cross-references: Markdown links like [RFC 0030](../rfcs/0030-slug.md) break on rename
External bookmarks: Browser bookmarks, shell aliases break
SQLite file_path: Must update documents.file_path on every rename

Mitigation strategies:

Update file_path in store on every status change (already touches store + markdown)
Cross-references use title-based lookups, not filename — most survive
git mv preserves history tracking
Accept that external bookmarks break (they already break on file deletion)

Spike-Specific Requirements

The user specifically wants to see spike outcomes from filenames:

Outcome	Meaning	Proposed Suffix
in-progress	Active investigation	`.wip` or no suffix
complete: no-action	Dead end	`.done`
complete: decision-made	Resolved with decision	`.done`
complete: recommends-implementation	Needs RFC	`.rfc` or `.done-rfc`

RFC-Specific Requirements

Status	Proposed Suffix
draft	`.draft` or no suffix
accepted	`.accepted`
in-progress	`.wip`
implemented	`.impl`
superseded	`.super`

Status Abbreviation Vocabulary

A consistent set of short status tags across all document types:

Tag	Meaning	Used By
(none)	Active/in-progress/draft (default)	All types
`.done`	Complete/closed/recorded	Spike, Audit, Postmortem
`.impl`	Implemented	RFC, ADR, PRD
`.super`	Superseded	RFC
`.archived`	Archived/inactive	Runbook

Findings

Question	Answer
Can status live in filenames?	Yes — no internal code parses filenames for status
Best approach?	Option A (status suffix) or Option C (subdirectories) — needs alignment dialogue
Does this integrate with RFC 0030?	Yes — timestamp + status suffix: `2026-01-26T0856Z-slug.done.md`
What about the rename problem?	Manageable — `git mv` + store update + title-based lookups survive
Biggest risk?	Cross-reference breakage in markdown files

Outcome

Recommends implementation. This should supersede RFC 0030 by incorporating both ISO 8601 timestamps AND status-in-filename into a unified "Document Lifecycle Filenames" RFC.

5.7 KiB Raw Blame History