ff8d38a9a8
# Conflicts: # docs/architecture.md # docs/cordis-catalog/events-and-services.md # docs/core-data-structures/core.md # docs/module-graph.md # docs/tool-catalog/tools.md # packages/README.md # packages/core/README.md # packages/core/tools/tests/gen-tool-catalog.spec.ts # packages/support/README.md # packages/support/ui-stdio/README.md # packages/ui/acp-agent/tests/built-bin.e2e.ts # packages/ui/acp/README.md # packages/ui/stdio-agent/README.md # packages/ui/stdio-agent/package.json # packages/ui/stdio-agent/src/index.ts # packages/ui/stdio-agent/src/stdio-chat.ts # packages/ui/stdio-agent/tests/built-bin.e2e.ts # packages/ui/stdio-agent/tests/readline.spec.ts # packages/ui/stdio-agent/tests/stdio-chat.spec.ts # packages/web/web/package.json # packages/web/web/tsconfig.json # pnpm-lock.yaml # scripts/gen-tool-catalog.ts
20 KiB
RFCs
One kind of design doc lives here. An RFC records a decision or proposal that shapes this codebase — the why and what we gave up, the parts code and docs can't carry.
Layout and naming
Every RFC has two axes, both encoded in its path — {lifecycle}/{class}/yyyy-mm-dd-topic-title.md:
- Lifecycle (the top-level folder) is the RFC's status, and an RFC moves between folders as that status changes:
proposed/— proposals reviewed before implementation; not yet built (or only partly).implemented/— the decision shipped. The file records what was decided and what was rejected, and is kept current with what actually shipped: when the code later moves a file, renames a package, or changes a key/default, the RFC is updated in the same change to match (facts only — paths, names, structure — not the decision itself). See implemented/AGENTS.md.rejected/— the proposal was considered and declined. Kept for the record so the rejection isn't re-litigated.
- Class (the nested folder) is the kind of decision — see Classification below.
The date in the filename is when the topic was first proposed (per git history). Cross-references between RFCs use relative markdown links ([topic](../../implemented/architecture/2026-…-….md)) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.
Classification
Each RFC is filed under exactly one class — the kind of decision it records. The class is encoded in the path (the folder is the label, so a file's location declares its class) and the set is closed: scripts/rfc-index.ts owns the canonical set, scripts/verify-rfc-classification.ts rejects any folder outside it, and the index tables below are generated from the tree (pnpm run gen-rfc-index rewrites the marker-delimited regions from each RFC's path, H1 title, and filename date; the gate fails when they are stale). Adding a new class means amending that const and this section, not just dropping a new folder. See the classification RFC for why the taxonomy is path-encoded and gated, and the index-generation RFC for why the tables are generated while this prose stays curated.
| Class | What it covers |
|---|---|
feature |
A new user- or model-facing capability. |
bug-fix |
Corrects a defect or closes a gap a postmortem surfaced. |
simplification |
Removes code, behavior, or surface area without adding a capability. |
architecture |
A structural decision about the shipped source — how packages relate, what the runtime vocabulary is. |
process |
Tooling, policy, or workflow around the code — gates, the package manager, vendoring — not runtime behavior. |
testing |
Test infrastructure and strategy. |
The architecture / process line: architecture is about the source we ship; process is the surrounding tooling and workflow. (refactor is deliberately absent — it overlaps simplification, whose discriminator, "does observable behavior change?", already covers it.)
When to write one
Write an RFC when a decision is durable (it shapes the codebase beyond a single function or package), contested (there was a real alternative a reasonable engineer might have chosen), and surprising (a future reader would otherwise ask "why on earth is it done this way?"). A proposal for substantial future work starts in proposed/; a decision already made starts in implemented/. Pick the class folder that matches the decision (see Classification).
Do NOT write one for a mechanical or local choice (a variable name, a one-file refactor), for anything already enforced and explained by a gate or a convention in AGENTS.md, or for a still-provisional decision tagged TODO(...) in the code — record those as TODOs and promote to an RFC only once they settle. An RFC is never edited into a different decision: supersede it with a new one and cross-link. (Editing an implemented/ RFC to track where its already-made decision now lives — a moved file, a renamed package — is not a different decision and is required, not forbidden; see implemented/AGENTS.md.)
Proposed
Feature
| Title | First proposed |
|---|---|
| Agent Client Protocol (ACP) support — drive the coding agent from external editors | 2026-06-14 |
| Multiplex concurrent ACP sessions over one connection | 2026-06-14 |
| Optional Code Mode — model writes TypeScript against an SDK of all tools | 2026-06-15 |
| Pre-tool input rewrite — a consistent design | 2026-06-30 |
Simplification
| Title | First proposed |
|---|---|
| Unify the agent id and the session id | 2026-06-20 |
Prune dead core-spine surface — SurfaceManager.invalidate(), the loop-internal exports, ToolExecutionResult.callId |
2026-07-04 |
Architecture
| Title | First proposed |
|---|---|
| Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern) | 2026-06-16 |
| Extract a generic long-running tool runtime | 2026-06-20 |
Process
| Title | First proposed |
|---|---|
| API extractor reports | 2026-06-11 |
| Architectural conformance — dependency rules and the adapter kit | 2026-06-11 |
| Supply chain checks and vendor drift verification | 2026-06-11 |
| Discover package inventories instead of maintaining static lists | 2026-06-20 |
Testing
| Title | First proposed |
|---|---|
| Deterministic tests, the replay invariant fixture, and race stress | 2026-06-11 |
| Mutation testing as the coverage counterweight | 2026-06-11 |
Implemented
Feature
Simplification
Architecture
Process
| Title | First proposed |
|---|---|
| Doc-sync enforcement | 2026-06-11 |
| Mechanical quality gates over prose guidelines | 2026-06-11 |
| tsdown for JS bundling instead of dumble | 2026-06-11 |
| Vendor Cordis as source, not npm dependencies | 2026-06-11 |
| pnpm as the package manager instead of Yarn 4 | 2026-06-16 |
| TSC-first build and one tsconfig | 2026-06-17 |
| Markdown cross-link validity linting | 2026-06-18 |
Core-data-structures catalog and the ts type-equiv drift gate |
2026-06-20 |
| Generated cordis events + services catalog | 2026-06-20 |
| Classify RFCs by kind via path-encoded subdirectories | 2026-06-20 |
| Bilingual documentation via paired sibling files and a pairing gate | 2026-07-02 |
| Generated tool-schema catalog (boot-and-harvest) | 2026-07-02 |
| Documentation graph index for maintainers and SDK users | 2026-07-03 |
| JSDoc completeness gate for the cordis surface | 2026-07-04 |
| Documentation tiers, budgets, and the ceiling gate | 2026-07-04 |
| Generate the RFC index tables | 2026-07-04 |
| Generated persistence log event catalog | 2026-07-04 |
Testing
| Title | First proposed |
|---|---|
| Property-based testing for protocol-shaped code | 2026-06-11 |
| ACP snapshot tests — record-once / replay-deterministic | 2026-06-19 |
| Real-API e2e in CI against the external DeepSeek API | 2026-06-19 |
Use session.jsonl as the only snapshot session-log artifact |
2026-06-20 |
| Persist the seed boundary so fork-child replay routes correctly | 2026-06-22 |
| Record fork and mixed spawn+fork snapshot scenarios | 2026-06-22 |
| Per-session snapshot replay for nested agents | 2026-06-22 |
| Hook snapshot matrix — end-to-end goldens for both bridges | 2026-07-04 |
| Single-source the acp-agent replay config | 2026-07-04 |
Rejected
Simplification
| Title | First proposed |
|---|---|
| Persist assembled assistant messages, not stream chunks | 2026-06-20 |
| Drop ACP session/load until resume has a product shape | 2026-06-20 |
Drop ACP terminal _meta rendering |
2026-06-20 |
| Drop bash full-output spill files | 2026-06-20 |
| Drop durable step boundary events | 2026-06-20 |
| Drop unused session lineage metadata | 2026-06-20 |
| Fold the persistence interface into dsh-session | 2026-06-20 |
| Collapse tool-owned UI presentation | 2026-06-20 |
| Retire mid-turn steering | 2026-06-20 |
| Return the ACP bridge to one live session per connection | 2026-06-20 |
| Truncate interrupted final turns on load | 2026-06-20 |
| Prune the unimplemented subagent seam vocabulary | 2026-07-04 |
Architecture
| Title | First proposed |
|---|---|
| Deep-readonly public surfaces | 2026-06-11 |
| Make the shared example base providerless | 2026-06-20 |