Tianyi Cui
e6fad266a6
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.
2.2 KiB
RFC: Make the shared example base providerless
Status: rejected — superseded by Extract example apps into packages, which moves the spine into a dsh-agent-core bundle and deletes the base*.yml files, so there is no shared base YAML left to rename.
Problem
The examples had two shared base files: examples/base-core.yml was providerless, while examples/base.yml included that core plus the real llm-deepseek adapter. Snapshot replay needs the providerless core with llm-replay, because loading the real adapter without a key throws. The normal demos need the real adapter. The result was a naming inversion: the file named base.yml was not the reusable base for all examples, while the true base was base-core.yml.
The split was understandable, but it made every config explanation longer. It also led to awkward test setup like a keyless smoke test carrying a dummy API key so an adapter could boot even though the model is not called.
Proposal
Rename the providerless core to examples/base.yml and make adapter selection explicit in each concrete example. The coding and ACP real configs add a tiny llm-deepseek include or local block; snapshot config adds llm-replay. Delete examples/base-core.yml.
The shared base should contain only provider-neutral services and tools: llm, sessions, system prompt, tools, agents, invariants, bash executor, and bash tool schemas. Anything that chooses a model provider belongs at the leaf config.
Acceptance criteria
examples/base.ymlis providerless.examples/base-core.ymlis deleted.- Real demo configs explicitly add the DeepSeek adapter.
- Snapshot replay config includes the same providerless base and its replay adapter.
- The examples README, example-specific READMEs, and RFC references stop explaining "base = base-core plus adapter".
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.