Task: Generate ERRORS.md — Unified Error / Result Taxonomy

Task: Generate ERRORS.md — Unified Error / Result Taxonomy

Objective

Produce an ERRORS.md that serves as the single source of truth for every error code the system can emit, its HTTP status, CLI exit code, UI message key, user action, retry semantics, log level, and owning bounded context. The document fixes a classification tree and per-class policy, pins the canonical error response body, publishes the complete alphabetical registry of stable UPPER_SNAKE error codes, names the wrapping and translation rules across component boundaries, states how each error is rendered on each surface, and commits a deprecation policy for retiring codes. An agent reading this document alone can — for any code the system emits — cite its HTTP status, CLI exit, UI key, user action, retry semantics, and owner, without opening INTERFACES.md or any IA.

ERRORS.md sits between INTERFACES.md (which owns the shape of error responses and per-endpoint error-code listings) and the per-surface IAs (which own user-facing error UX) and resolves them to one taxonomy. It is small, stable, widely cited, and read by IAs (for user-facing message copy), /spec (for the codes a unit may emit), /review (for contract conformance), and /system-verify (when diagnosing failures). The defining discipline — and the commonest violation — is codes are stable: once a code string is assigned, it is never reused, never re-meaning'd, never silently deleted.

Inputs

1. INTERFACES.md (required) — for the canonical error response shape and the per-endpoint error-code listings cited at EP-name boundaries. Every error code mentioned in an endpoint response in INTERFACES.md must have a registry row here.
2. Surface IAs (required — one per surface that exists in the project) — WEB_IA.md, CLI_IA.md, MOBILE_IA.md, TUI_IA.md, VOICE_IA.md. Only the IAs that were produced for this project are read; surfaces the project does not build have no IA and no column in § 5. Each IA's error-surface section names the ui_message_key or template it expects.
3. DOMAIN.md (required) — § 2 Bounded Contexts supply the owner_context value on every row; § 9 Invariants Index supplies the INV-NN references that certain codes signal (a uniqueness invariant violation surfaces as a specific code, named here).
4. Existing error handling code (optional, auto-discovered) — if source trees are present, scan throw, raise, panic, return Err(...), respondError(...) sites and collect codes already emitted that are not yet documented. Surface undocumented codes as rows or as open questions if the mapping is ambiguous.
5. Existing ERRORS.md (auto-discovered — only if refining) — if an ERRORS.md already exists at the expected path, read it fully. Every assigned code string is permanent. New codes take new unused strings (never reuse a retired code's string). Deprecated codes retain their row with deprecated_since / removed_in columns populated.

Read set size: 3 required (INTERFACES, DOMAIN, each surface IA in scope) + optional source scan + optional prior ERRORS. Read all IAs and INTERFACES.md end-to-end before drafting. Omitted reading causes two specific failure modes: codes cited in INTERFACES or an IA without a registry row (contract drift) and codes emitted by code that never reach the registry (silent divergence).

Workflow

Error taxonomy construction proceeds in seven phases: harvest, classification, canonical shape, registry, wrapping, per-surface mapping, and validation. Phases are sequential. Revisit earlier phases if a later one reveals a missing code or a contradiction.

Phase 1: Code Harvest

Collect every error code candidate from four sources:

• INTERFACES.md per-endpoint response listings — every code named in the errors: field of an endpoint. These are the externally-visible codes; every one must land in § 3.
• Surface IAs' error-surface sections — every ui_message_key an IA expects to render; the corresponding code must exist here.
• DOMAIN.md invariants — every INV-NN that is enforced at runtime typically signals through a specific code when violated. Name one code per enforced invariant, citing the INV-NN in the row's references column.
• Existing source code (if available) — throw, raise, panic, Err(...), error-response helpers. Normalise to UPPER_SNAKE. Codes found only in code with no INTERFACES / IA reference are either internal-only (log-level error or critical; never reach users) or missing from INTERFACES — surface as an open question if the boundary is unclear.

Deduplicate by meaning, not by spelling. NOT_FOUND and MISSING and UNKNOWN_RESOURCE are the same code in three forms; pick one canonical UPPER_SNAKE string. Record the rejected forms so the registry does not accumulate synonyms.

Phase 2: Classification Tree

Partition the harvested codes into three top-level classes and their conventional HTTP families: