From 7690e08e70be373d3d96d07deacb48024f36269f Mon Sep 17 00:00:00 2001 From: nesquena-hermes Date: Mon, 11 May 2026 02:45:38 +0000 Subject: [PATCH] docs(rfcs): establish docs/rfcs/ convention and polish turn-journal RFC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves docs/turn-journal-rfc.md → docs/rfcs/turn-journal.md, establishing the convention for future design documents on hermes-webui's data-at-rest and recovery surfaces. Adds docs/rfcs/README.md describing when an RFC applies (large changes, durability/recovery semantics, new infrastructure primitives) and the simple status header convention. Polish on turn-journal.md: - Added 3-line status header (Status / Author / Created) at top. - Light tone edits on two flourishes that read fine in a PR description but felt off in permanent repo documentation. Author's voice preserved throughout the rest of the document. Co-authored-by: ai-ag2026 <261867348+ai-ag2026@users.noreply.github.com> --- .gitignore | 2 ++ docs/rfcs/README.md | 35 +++++++++++++++++++ .../turn-journal.md} | 8 +++-- 3 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 docs/rfcs/README.md rename docs/{turn-journal-rfc.md => rfcs/turn-journal.md} (96%) diff --git a/.gitignore b/.gitignore index 0edd66af..529563ba 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,8 @@ Thumbs.db docs/* !docs/ui-ux/ !docs/ui-ux/** +!docs/rfcs/ +!docs/rfcs/** !docs/docker.md !docs/supervisor.md !docs/troubleshooting.md diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md new file mode 100644 index 00000000..d86c5ed9 --- /dev/null +++ b/docs/rfcs/README.md @@ -0,0 +1,35 @@ +# RFCs + +This directory holds design documents for hermes-webui features that are +worth thinking through in writing before (or alongside) implementation — +typically when the change touches durability, recovery, schema, or cross- +cutting infrastructure. + +## Conventions + +- One file per RFC. Filename is the topic (kebab-case), not a number. +- Top of every RFC carries a small header: + + - **Status:** Proposed | Accepted | Implemented | Withdrawn + - **Author:** @github-handle + - **Created:** YYYY-MM-DD + +- Sections usually include: Problem, Goals, Non-goals, Proposal, Open + questions, Rollout plan. Skip what doesn't apply. +- An RFC is a starting point for review. Comments and revisions land via PR + edits, not separate discussion threads. + +## When to file an RFC + +- The change is large enough that you want consensus before writing code. +- The change touches data-at-rest formats or recovery semantics. +- The change introduces a new architectural primitive (journal, queue, + scheduler, cache layer) that other features will build on. +- A reviewer asks for one during code review. + +When in doubt, just ship the code — small features don't need RFCs. + +## Current RFCs + +- [`turn-journal.md`](turn-journal.md) — Crash-safe WebUI turn journal for + recovering interrupted chat submissions. diff --git a/docs/turn-journal-rfc.md b/docs/rfcs/turn-journal.md similarity index 96% rename from docs/turn-journal-rfc.md rename to docs/rfcs/turn-journal.md index a62479f3..6c0924f4 100644 --- a/docs/turn-journal-rfc.md +++ b/docs/rfcs/turn-journal.md @@ -1,5 +1,9 @@ # RFC: WebUI Turn Journal for Crash-Safe Chat Submissions +- **Status:** Proposed +- **Author:** @ai-ag2026 +- **Created:** 2026-05-11 + ## Problem A WebUI chat turn crosses several durability boundaries: @@ -19,7 +23,7 @@ The missing primitive is a small write-ahead journal for turns: record the submi - Preserve the exact user-submitted turn, including attachments metadata, before any provider or worker work starts. - Make crash recovery deterministic: a submitted-but-unfinished turn can be reported or reconstructed without guessing. - Keep the journal append/update format simple enough for startup recovery, CLI audit, and future API repair endpoints. -- Avoid turning recovery into a background daemon. This is storage hygiene, not a tiny cult with a scheduler. +- Avoid turning recovery into a background daemon. This is storage hygiene, not a long-running service. ## Non-goals @@ -151,4 +155,4 @@ The first implementation PR should be deliberately small: - one call site: append `submitted` before worker start - audit-only report of pending journal turns -Do **not** combine the first implementation with replay/repair. Replay is where footguns rent office space. +Do **not** combine the first implementation with replay/repair. Replay is where most of the bugs in WAL systems live; ship the writer and audit first, prove the format, then add repair.