docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus

Define the in-file RFC contract in docs/rfc/README.md § The file format: the header block (`# RFC: <title>` plus a dateless Status enum cross-checked against the lifecycle folder), the per-lifecycle body skeleton (a Problem opener everywhere; Proposal/Alternatives considered/ Acceptance criteria/Risks in proposed/; present-tense Decision/ Consequences with proposal-era headings banned in implemented/; the frozen proposal shape in rejected/), and a mandatory Alternatives considered section with a date-fenced grandfather comment for pre-format RFCs whose alternatives are not reconstructible from the record. Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the enum, 29 Context openers become Problem, the 39 legacy-format XXX debt markers are resolved and banned from reappearing, proposal-era sections in implemented RFCs are rewritten to shipped reality (including the web/fs/subagent seam RFCs' migration plans and test checklists, closing the doc-tiers deferred-work item on the web seam), every RFC gains an Alternatives considered section or the grandfather comment, and the bilingual pair is re-mirrored and re-recorded. Move the generated index tables out of README.md into a fully generated docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and verify-rfc-classification checks its freshness and rejects index-shaped rows in the curated README — which makes room for the format contract to live in the README front door instead of a separate FORMAT.md. The decision record, and the first RFC written in the new format, is docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.
2026-07-05 22:58:25 +08:00
parent d5cb3297ad
commit e6fad266a6
123 changed files with 1221 additions and 847 deletions
@@ -2,8 +2,6 @@

 Status: rejected — the pervasive `DeepReadonly<T>` type flip was rejected in favor of an always-on `deriveMessages` clone plus dev-mode `Object.freeze` + invariants. The immutability *goal* shipped via that alternative; see [dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).

-<!-- XXX: legacy ADR/RFC body format, not yet normalized to a unified RFC template. -->
-
 ## Problem

 The session log is append-only by contract, but `session.events` returns `readonly SessionEvent[]` whose *elements* are mutable: a plugin can reach in and rewrite history (`events[0].data.content.push(...)`), silently breaking replay equivalence and the derived-history guarantee. The same applies to derived messages and prompt assemblies passed through waterfalls — mutation is sometimes the intended idiom (waterfall middleware mutates the request) and sometimes corruption (mutating a *logged* event), and the types don't distinguish.
@@ -26,3 +24,5 @@ Introduce `DeepReadonly`, flip the session read paths, fix resulting compile err
 ## Risks

 `DeepReadonly` types can produce noisy errors at waterfall boundaries where mutation IS the API — keep the mutable/readonly boundary exactly at "logged vs in-flight" and document it in the session README.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ The shared base should contain only provider-neutral services and tools: `llm`,
 ## What we give up

 Real demos lose one layer of convenience: each must opt into the adapter. That is the right default for examples, because adapter choice is the variable part and providerless wiring is the shared product core.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -30,3 +30,5 @@ The canonical user session no longer reconstructs the exact token stream of an o
 ## Related

 This supersedes the chunk-persistence choice in [session persistence](../../implemented/architecture/2026-06-14-session-persistence.md) and affects [ACP snapshot tests](../../implemented/testing/2026-06-19-acp-snapshot-tests.md), whose current replay plugin derives its script from `assistant/chunk` events.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -23,3 +23,5 @@ For now, ACP starts fresh sessions only. `initialize` advertises `loadSession: f
 ## What we give up

 An editor cannot reopen a prior persisted session through ACP. That is a real product feature, but the current implementation is ahead of the UX and ties the bridge to token-level log replay. Keeping persistence while dropping editor load narrows the bridge to the workflow it can currently present cleanly.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ This proposal is narrower than [collapsing tool-owned UI presentation](2026-06-2
 ## What we give up

 Zed users lose the dedicated terminal card: no cwd header, terminal display, or exit pill. They still see the command and output as plain content. That is a reasonable simplification while the ACP bridge is still unreleased and the `_meta` keys are a convention rather than a standard.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ This proposal can land independently of [a generic long-running tool runtime](..
 ## What we give up

 A model or user cannot recover the omitted prefix of a huge command output from a temp file. That is acceptable until there is a real artifact service. The current spill path is too much bespoke machinery for a feature whose lifecycle and permissions are not designed.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -26,3 +26,5 @@ The invariants plugin should enforce that step-scoped events have valid positive
 ## What we give up

 The log no longer records "a model request started but produced no event before the process died" as a durable fact, and no longer has an explicit "this step completed" marker. That loss is not acceptable while the session log is the durable replay and audit surface.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ If lineage returns, decide then whether it belongs in the immutable header, a se
 ## What we give up

 The codebase loses a ready-made lineage hook for future fork/sub-agent UX. That is intentional. The field is easy to reintroduce when the feature exists, and the unreleased stance lets the format change without migrations.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ The implementing PR should update the [capability seams](../../implemented/archi
 ## What we give up

 `dsh-session` becomes heavier: it owns both the in-memory log and the persistence interface. That is the trade. If third-party persistence backends were already a public ecosystem, the separate interface package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external consumer.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -12,6 +12,8 @@ The real first-party use is bash presentation for ACP. That is too little eviden

 Remove tool-owned UI presentation callbacks for now. The canonical tool events already carry the tool name, raw argument string, result content, and error state. UIs render a generic tool card from those fields. Tool-specific rich rendering can return later as a tagged render-intent union after there are at least two real tools and two real consumers to validate the vocabulary.

+## Alternatives considered
+
 As a smaller alternative, replace the current optional-field bag with one explicit union in a single PR; but if the goal is simplification, the stronger move is to delete the callbacks and keep the generic path.

 ## Acceptance criteria
@@ -31,3 +31,5 @@ A user cannot add same-turn steering content while a model is between tool steps
 ## Related

 This pairs naturally with [dropping durable step boundaries](2026-06-20-drop-durable-step-boundaries.md), because removing same-turn steering and `agent/turn-continuation` leaves tool calls as the only reason a turn contains multiple model steps.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -25,3 +25,5 @@ Remove the multi-session maps and demux where a single `SessionRecord | undefine
 ## What we give up

 An ACP client cannot host several concurrent conversations on one server process. That is a meaningful capability cut. The simpler model is still reasonable for an unreleased harness: one editor conversation maps to one agent process, and cross-session permission/background-task isolation stops being a live correctness burden.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -30,3 +30,5 @@ A crash can lose real work from the final turn: assistant text, tool calls, and
 ## Related

 This is a direct simplification of [session persistence](../../implemented/architecture/2026-06-14-session-persistence.md) and [turn enclosure](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md). It also removes much of the motivation for durable step boundary events, making [drop durable step boundary events](2026-06-20-drop-durable-step-boundaries.md) smaller.
+
+<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -21,7 +21,9 @@ Adjacent surface examined and deliberately left alone: `SubagentService.getProvi

 This is the seam-vocabulary echo of [prune dead methods from the persistence seam](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md): members every implementation must declare for nobody — weaker even, since here zero implementations exist.

-## Why not keep it?
+## Alternatives considered
+
+### Why not keep it?

 The two-kinds-of-capability design is the seam RFC's headline, and re-adding `outputSchema` later touches several files. But the design survives with `depthLimit` as its live example and the RFCs as its record, and the seam RFC itself concedes the shipped `toolFilter` shape is wrong (real enforcement needs a `tools/pre-execute` deny in the child's context, not schema filtering) — that deny primitive exists on the interception seams, so re-adding against a real implementing provider will pin a better contract than the current speculative one.