# Tasks — document-site-middleware-integration

## 1. Authoring

- [x] 1.1 Read the original `add-api-plugin-site` proposal exclusion paragraph and confirm the no-hard-dep constraint.
- [x] 1.2 Author `proposal.md` with `### Source mapping` + `### Excluded from this change` + `### Affected dependents`.
- [x] 1.3 Author the spec delta in `specs/api-plugin-site/spec.md` with `## ADDED Requirements` + `## MODIFIED Requirements`.

## 2. Implementation

- [x] 2.1 Add `src/integration/middleware-recommendations.ts` exporting `MiddlewareRecommendation` type + `MIDDLEWARE_RECOMMENDATIONS` constant with one recommendation per route group (public-resolve, public-read, private-write).
- [x] 2.2 Add sibling `src/integration/middleware-recommendations.md` (≥200 words, Purpose / Features / Basic / Advanced / API Reference / Implementation Notes).
- [x] 2.3 Add `src/integration/middleware-composition.integration.test.ts` — real Hono app composing `createAuditMiddleware`, `rateLimit`, and `createPrivateSiteRoutes`; assert site behaviour preserved, rate-limit headers set, audit event recorded.
- [x] 2.4 Update `src/routes/private-routes.md` with "Recommended middleware" section.
- [x] 2.5 Update `README.md` with "Middleware composition" subsection linking the doc + recommendations.
- [x] 2.6 Add `docs/middleware-integration.md` (package-level guide).
- [x] 2.7 Update `src/index.ts` to re-export `MIDDLEWARE_RECOMMENDATIONS` and `MiddlewareRecommendation`.
- [x] 2.8 Update `package.json` to add `@suaveplan/api-plugin-rate-limit` + `@suaveplan/api-plugin-audit` as `devDependencies` only.
- [x] 2.9 Update the `api-plugin-site.spec-conformance.test.ts` surface count to include the new export.

## 3. Pre-archive gates

- [x] 3.1 `bunx biome check src/` clean.
- [x] 3.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-site` green.
- [x] 3.3 `bunx turbo test:coverage --filter=@suaveplan/api-plugin-site` ≥ 100% on every metric.
- [x] 3.4 `bun scripts/openspec-conformance.ts @suaveplan/api-plugin-site` returns 0 errors.
- [x] 3.5 `bunx turbo build --filter=@suaveplan/api-plugin-site` green.
- [x] 3.6 Banned-pattern scan returns no hits (`@deprecated`, `TODO`, `FIXME`, `ts-ignore`, `ts-expect-error`, `.skip`, `.only`, ` any `, `console.log`).
- [x] 3.7 Test-runner import scan returns no hits (`from "vitest"` / `from "bun:test"`).
- [x] 3.8 Sibling `.md` scan returns no missing-doc hits.
- [x] 3.9 No bare versions in `package.json`.

## 4. Archive

- [ ] 4.1 Fold `specs/api-plugin-site/spec.md` into `openspec/specs/api-plugin-site/spec.md`.
- [ ] 4.2 `mv openspec/changes/document-site-middleware-integration openspec/archive/2026-05-19-document-site-middleware-integration`.