docs(rfc): classify RFCs by kind via path-encoded subdirectories

Add a second axis to every RFC — its class (feature, bug-fix, simplification, architecture, process, testing) — encoded in the path as docs/rfc/{lifecycle}/{class}/file.md. The folder is the label, so the closed set is enforced by structure rather than a parsed field. Two new doc-sync gates back it: - verify-rfc-classification: every RFC sits in a valid class folder and the README index lists it under the matching lifecycle→class heading. - verify-doc-refs: every docs/*.md path cited in a packages|examples TS comment resolves — closes a drift class verify-md-links can't see, and catches the four comment refs this reorg moved. The README gains a Classification section explaining the taxonomy and per-class index sub-sections. A self-referential process RFC records why the scheme is path-encoded and gated.
2026-06-20 22:29:45 +08:00
parent 906705e353
commit 605587e79c
92 changed files with 673 additions and 293 deletions
@@ -0,0 +1,26 @@
+# RFC: Structured error taxonomy
+
+Status: implemented (accepted 2026-06-14)
+
+<!-- XXX: legacy ADR/RFC body format, not yet normalized to a unified RFC template. -->
+
+## Context
+
+Failures crossed seams as bare strings. A tool error flattened to a text block — name, code, and stack lost — so a future sandbox/retry plugin couldn't tell ENOENT from EACCES, and the model got less actionable feedback than it could. A non-Error throw degraded further: the loop wrapped it in `new Error(String(x))`, dropping any code. And `LlmError` was the only typed error in the system, with no shared base, so there was nothing for a consumer to `instanceof` against generically.
+
+This is the last of the runtime-validation / error-taxonomy pieces and the one the user was most skeptical of, so it was deliberately built **last and in isolation**: the earlier PRs (arg validation, dev invariants) threw plain `Error`s with a `code` field, decoupled from any shared base, so this change is a pure upgrade and is independently revertible without unpicking them.
+
+## Decision
+
+A single `HarnessError extends Error` base in `dsh-llm` (the leaf package every other imports — no new dependency edge): a stable `code` distinct from `message`, `cause` chaining via `ErrorOptions`, and `name` defaulting to the subclass. `isHarnessError` narrows at seams.
+
+- `LlmError`, `ToolArgsError` (dsh-tools), and `InvariantError` (dsh-invariants) now extend it, keeping their existing codes.
+- `ToolExecutionResult` gains optional `error: { name, code }`, populated in the registry's catch when the thrown value is a `HarnessError`. The agent loop forwards it onto the `tool/result` session event (which gained the same optional field), so the structured failure survives into the log for retry/sandbox plugins and replay. The model-facing text block is unchanged.
+- The loop's `toError` wraps a non-Error throw in a `HarnessError` (`code: 'UNKNOWN'`, original chained as `cause`) instead of a bare `Error`, so even a bad throw carries a routable code into the session `error` event (which already surfaced `code`).
+
+## Consequences
+
+- Errors are machine-routable end-to-end: a plugin can branch on `error.code` rather than substring-matching a message.
+- One base class is imported widely, but it lives in the package everyone already depends on, so the cost is a single import, not a new edge.
+- `deriveMessages` does not surface `error` into model history — the model still sees the text block; the structured field is for code and replay.
+- Reverting this PR returns the earlier errors to plain `Error`+`code` form; nothing else in the stack depends on the shared base.