docs(plan-9): doc-pass slice 1 — CLAUDE.md, core-shared AGENTS, architecture, plan-8 annotations

First slice of the combined Plan 8 + Plan 9 doc-update pass:
- CLAUDE.md Key Conventions: append schema-in-use-case, presenter,
  controller unknown input, feature-scoped tRPC error mapping, public
  surface split (./ui)
- packages/core-shared/AGENTS.md: document defineErrorMiddleware export
  + t re-export from trpc/init
- docs/superpowers/plans/2026-05-05-plan-8-*.md and matching spec:
  one-line note that some controller/router patterns shifted in Plan 9;
  link to the Plan 9 refactor log
- docs/architecture/overview.md: data-flow box now shows xProcedure +
  xInputSchema + xOutputSchema.parse + presenter + middleware lanes;
  three explanatory paragraphs added (schemas, presenter, error mapping)
- docs/architecture/dependency-flow.md: app-side ./ui subpath note,
  allowed/disallowed examples updated for Plan 9 paths

Remaining doc-pass items (root AGENTS.md, per-feature AGENTS.md ×5,
core-testing AGENTS.md, adding-a-feature.md, tdd-workflow.md,
testing-strategy.md, vertical-feature-spec.md) follow in subsequent
commits — to be dispatched in parallel.
This commit is contained in:
2026-05-06 16:43:13 +02:00
parent 3dc843ca4b
commit ef2b8e300e
6 changed files with 60 additions and 8 deletions

View File

@@ -31,6 +31,10 @@
Composition exceptions:
core-api → @repo/<feature>/api (subpath only)
core-cms → @repo/<feature>/cms (subpath only)
App-side feature subpaths (Plan 9):
@repo/<feature> — contracts (types, errors, schemas, IUseCase aliases, router type, constants)
@repo/<feature>/ui — UI artifacts (query builders, components)
```
## Concrete examples
@@ -41,6 +45,8 @@ Allowed:
import { appRouter } from "@repo/core-api";
import { NextTrpcProvider } from "@repo/core-trpc/next";
import { bindProductionBlog } from "@repo/blog/di/bind-production";
import { signInInputSchema, type SignInInput } from "@repo/auth"; // contracts (Plan 9)
import { articleBySlugQuery } from "@repo/blog/ui"; // queries (Plan 9)
// in packages/blog
import { slugifyIfMissing } from "@repo/core-shared/payload";
@@ -63,9 +69,17 @@ import { articles } from "@repo/blog/src/integrations/cms/collections/articles";
// in packages/core-shared
import { blogRouter } from "@repo/blog/api"; // ❌ core → feature
import { ArticleNotFoundError } from "@repo/blog"; // ❌ core → feature
// (defineErrorMiddleware takes Error
// constructors as args from features —
// core-shared never imports them)
// in packages/core-trpc
import { someBlogThing } from "@repo/blog"; // ❌ core → feature (only core-api/core-cms have exception)
// in apps (using the wrong subpath)
import { articleBySlugQuery } from "@repo/blog"; // ❌ queries live on ./ui
import { Article } from "@repo/blog/ui"; // ❌ types live on the root subpath
```
## Enforcement strategy