Files

T

Tianyi Cui 09f131f78e docs(rfc): fold PR #139 's simplification sweep into this set

Deduplicate the parallel sweep from codex/exhaustive-simplification-rfcs
(merged in the parent commit) against the twelve RFCs already here, on
the merits per item:

Ported (rewritten to this set's evidence standard):
- fold-stdio-ui-helper — verified: dsh-stdio-agent is the only runtime
  importer; the fold resolves the documented product-app-depends-on-
  support-package tension. The false acp-agent analogy is replaced with
  the real distinction (protocol product surface vs one app's front-door
  scaffolding).
- generate-rfc-index-tables — verified: the classification RFC records
  rejecting generation; the index tables are the repo's only
  systematically conflicting docs region. Process framing made timeless.

Consolidated into existing owners:
- web searchStatus()/fetchStatus()/WebCapabilityStatus (verified: zero
  production callers; the tool-web README and architecture.md claims are
  drift) → drop-web-providers-change-event, renamed
  drop-unconsumed-web-observation-surface.
- hook/result.durationMs (unread, nondeterministic, normalizer-scrubbed)
  and the double-defaulted defaultTimeoutMs knob →
  tighten-hook-protocol-contract.
- the exercised-but-unadvertised exec.arguments mutation path (a
  tool-bash integration shim rewrites through it) → a sanction-or-seal
  note in the pre-tool-input-rewrite proposal.
- the dormant-guard critique of subagent depth machinery → recorded in
  prune-unimplemented-subagent-vocabulary as the considered-and-rejected
  alternative, with the keep sharpened (uncapped-today acknowledged;
  wiring the cap is the completion, not deletion). getProvider()/list()
  and lastAssistantMessage recorded as examined-and-kept (bash-revert
  precedent; observe-enrich recorded keep).

Not ported (with reasons):
- tools/change + system-prompt/change removal — recorded keeps in the
  adapter-change RFC, unengaged by the sweep; no new facts.
- LlmService.models() — flagged by both surveys, but two lines with a
  plausible consumer: TODO-or-drive-by territory per the RFC bar, not
  a proposal.
- SchemaProp.default RFC — already XXX(unused-default)-tagged; the RFC
  bar excludes TODO-tracked provisional cleanups.
- PreToolDecision 'ask' removal — FIXME(permissions)-anchored deferral
  with the permission system as its named consumer.
- Codex bridge Config.model, merged systemMessages — wire-faithful
  tested surface / README-documented deferral.

Their in-code TODO notes (acp-test-harness, hook-snapshot-noise,
catalog-type-links) and the stale hook-prompt-block name fixes ride the
merge unchanged.

2026-07-04 12:53:21 +08:00

3.0 KiB

Raw Blame History

RFC: Generate the RFC index tables

Status: proposed

Problem

docs/rfc/README.md's per-lifecycle/per-class tables are hand-maintained even though every fact in them is derivable: an RFC's path encodes lifecycle and class, its filename encodes the first-proposed date, and its H1 carries the title. scripts/verify-rfc-classification.ts already walks the tree and cross-checks the index — the expensive parsing exists; it reports instead of writing.

The tables are also the repo's highest-contention docs hotspot: every proposal wave appends rows to the same few lines, so concurrent RFC branches conflict precisely there while agreeing everywhere else, and each conflict is resolved by hand-merging rows whose content the filesystem already knows. The classification RFC records rejecting auto-generation to keep the file curated — but the curated part of the README is the prose, and the prose never conflicts; only the mechanical tables do.

Proposal

Keep the curated prose; generate the tables. Add a gen-rfc-index mode (a --write flag on verify-rfc-classification.ts, or a sibling script sharing its walker) that scans the RFC tree, reads each H1, derives the date from the filename, and rewrites the table rows under stable generated markers per ## {Lifecycle} / ### {Class} section; verify-rfc-classification asserts freshness — the gen-cordis-catalog/verify-cordis-catalog pattern. The class and lifecycle sets stay closed in the script. The implementing PR amends the classification RFC's rejected-alternatives record per implemented/AGENTS.md, since this supersedes that recorded choice.

Why not keep the verifier-only model?

It catches mistakes but still makes every proposal edit a shared hotspot, and a failed verifier is strictly more annoying than a generator for a purely mechanical row: the author has already named and placed the file; the index copy adds no information. This is the same hand-list-versus-derivation judgment the package-inventory proposal applies to tsconfig references and knip stanzas — applied to the one list that demonstrably conflicts.

Acceptance criteria

pnpm run gen-rfc-index (or the chosen spelling) rewrites only the generated table regions; verify-rfc-classification fails when they are stale and passes after regeneration.
Adding, moving, or deleting an RFC requires editing only the RFC file itself; the rows are produced from path + H1 + filename date.
The prose outside the generated markers is untouched by the generator; pnpm run doc-sync passes.

Risks

Generated regions inside a curated file need explicit markers so ownership is obvious to reviewers. Reading H1s makes a malformed header a generator error — useful pressure, and it should fail clearly. This supersedes an implemented process decision; amending that RFC's record is part of the change, not optional.

3.0 KiB Raw Blame History