From 61baaae99a517b740e95e28642e07d711ce1d0b6 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 6 May 2026 11:00:47 +0200 Subject: [PATCH] docs(refactor-log): scaffold Plan 9 input/output unification changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Empty section template plus the doc-update checklist that the post-Plan-9 follow-up pass will work through (combined with the still- pending Plan 8 items so docs are written once). Spec: docs/superpowers/specs/2026-05-06-input-output-unification-design.md §10, R30. --- .../2026-05-06-input-output-unification.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md diff --git a/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md b/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md new file mode 100644 index 0000000..d864073 --- /dev/null +++ b/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md @@ -0,0 +1,101 @@ +# Refactor Changelog — Input/Output Unification + Presenter + Error Middleware + Public-Surface Cleanup + +**Started:** 2026-05-06 +**Spec:** [2026-05-06-input-output-unification-design.md](../specs/2026-05-06-input-output-unification-design.md) +**Plan:** [2026-05-06-plan-9-io-unification.md](../plans/2026-05-06-plan-9-io-unification.md) +**Branch:** feature/io-unification + +This document captures every architectural change made during Plan 9 +execution, organized by category. After the plan is merged, use the +"Doc update checklist" at the bottom to update external docs in a +single follow-up pass — combined with the still-pending Plan 8 +doc-update items so docs are written once for the post-Plan-9 state. + +--- + +## 1. Files added + +(populated as work progresses) + +## 2. Files modified + +(populated as work progresses) + +## 3. Pattern changes (code-level) + +### 3.1 Use-case files — input + output schemas + runtime parse +(populated when use cases are migrated) + +### 3.2 Controller files — presenter + unknown input + view return type +(populated when controllers are migrated) + +### 3.3 tRPC integration — feature-scoped procedures, schema reuse from use cases +(populated when routers are migrated) + +## 4. Error-middleware adoption + +(populated when defineErrorMiddleware is wired in core-shared and consumed by features) + +## 5. Public-API surface + +### 5.1 ./ui subpath added per feature +(populated as features adopt the subpath) + +### 5.2 Feature root index.ts cleanup +(populated as features clean up their root exports) + +## 6. Test additions + +### 6.1 R25 — output-validation tests (use case) +(populated when use cases gain malformed-input "repo lied" tests) + +### 6.2 R26 — router error-mapping tests +(populated when feature routers gain TRPCError-translation tests) + +### 6.3 R27/R28 — presenter shape tests +(populated when controllers with non-identity presenters add view-shape assertions) + +## 7. Open issues / deferred decisions + +(populated as encountered) + +--- + +## Doc update checklist (deferred — combined with paused Plan 8 doc pass) + +After Plan 9 lands, the still-pending Plan 8 doc-update items resume +and now also pick up Plan 9 rules. Each item below covers BOTH plans' +material so we touch every file once. + +- [ ] `CLAUDE.md` — Key Conventions: append schema-in-use-case rule, presenter rule, controller `unknown` input rule, `./ui` subpath rule, schema-export-from-root rule +- [ ] `AGENTS.md` (root) — Per-Package Conventions: document `./ui` subpath, schema reachability from feature root, factory-bound use cases / controllers (carry-over from Plan 8) +- [ ] `docs/guides/adding-a-feature.md` — restructure to use the Plan-9 use-case template (with input + output schemas + parse), the Plan-9 controller template (with presenter), and the new `procedures.ts` step (per-feature error map) +- [ ] `docs/guides/tdd-workflow.md` — update mock decision tree + worked example to factory injection (Plan 8) + R25 output-validation test pattern (Plan 9) + R26 router-error-mapping test pattern (Plan 9) +- [ ] `docs/guides/testing-strategy.md` — Mocking section: direct factory injection (Plan 8); R25/R26/R27/R28 test obligations (Plan 9) +- [ ] `docs/architecture/vertical-feature-spec.md` — §6 file shape: schemas + presenter + procedures.ts; §10 testing: R25/R26/R27/R28 +- [ ] `docs/architecture/overview.md` — data-flow box: add input schema, output schema, presenter, error-middleware lanes +- [ ] `docs/architecture/dependency-flow.md` — verify (no expected change beyond a `./ui` mention) +- [ ] `docs/decisions/adr-012-lazar-conformance.md` — append note that input/output unification + presenter + error middleware land in ADR-013 +- [ ] `docs/decisions/adr-013-input-output-unification.md` — created in this plan's final task (Task 9); link from prior ADRs +- [ ] Per-feature `AGENTS.md` (auth/blog/media/marketing-pages/navigation) — Plan 8 file paths + Plan 9 schema/presenter/procedures patterns +- [ ] `packages/core-testing/AGENTS.md` — note R25/R26 test patterns +- [ ] `packages/core-shared/AGENTS.md` — document `defineErrorMiddleware` and the `t` re-export +- [ ] Plan 8 plan/spec — add a one-line annotation that some controller/router patterns shifted in Plan 9; link to this changelog + +--- + +## Notes for the doc-update pass author + +When updating external docs, apply these substitutions globally: + +| Old reference | New reference | +|---|---| +| Use case takes `{ x }` directly typed | Use case takes `XInput` (`z.infer`); schema lives in same file | +| Use case returns `Promise` | Use case returns `Promise` validated by `xOutputSchema.parse(...)` | +| Controller imports `z` and defines local `inputSchema` | Controller imports `xInputSchema` from the use-case file | +| Controller input typed `Partial>` | Controller input typed `unknown` | +| Controller returns `Promise` | Controller has `function presenter(value: XOutput)`; returns `Promise>` (or `Promise` for void use cases) | +| Router uses `publicProcedure` from `core-shared/trpc/init` | Router uses feature's `xProcedure` from `./procedures` | +| Router redefines input schema as `z.object({...})` in `.input(...)` | Router uses `.input(xInputSchema)` imported from the use-case file | +| Domain error reaches the wire as a generic `TRPCError({ code: "INTERNAL_SERVER_ERROR" })` | Domain error mapped to specific code by `defineErrorMiddleware` in `procedures.ts` | +| Frontend imports `articleBySlugQuery` from `@repo/blog` | Frontend imports from `@repo/blog/ui` |