Scaffold miniroute routing/middleware kernel

4 files changed, 123 insertions, 0 deletions

diff --git a/docs/adr/0001-kernel-not-framework.md b/docs/adr/0001-kernel-not-framework.md
new file mode 100644
index 0000000..e77cc2d
--- /dev/null
+++ b/docs/adr/0001-kernel-not-framework.md
@@ -0,0 +1,22 @@
+# ADR 0001: A Routing Kernel, Not a Framework
+
+- Status: Accepted
+- Date: 2026-08-17
+
+## Context
+
+The routing/middleware logic from brett-parson.com is being extracted into a
+reusable package. The temptation is to grow it into a general-purpose web
+framework.
+
+## Decision
+
+miniroute ships routing, matching, middleware composition, and controller
+resolution only. It deliberately owns no HTTP object implementations, no
+container, no templating, no database, no session, and no configuration.
+
+## Consequences
+
+- The package stays small enough to explain end-to-end.
+- Consumers own their concrete Request/Response and dependency wiring.
+- Reuse is broad because the kernel makes no assumptions about an app's stack.
diff --git a/docs/adr/0002-attribute-based-route-declaration.md b/docs/adr/0002-attribute-based-route-declaration.md
new file mode 100644
index 0000000..d1d4c79
--- /dev/null
+++ b/docs/adr/0002-attribute-based-route-declaration.md
@@ -0,0 +1,24 @@
+# ADR 0002: Attribute-Based Route Declaration
+
+- Status: Accepted
+- Date: 2026-08-17
+
+## Context
+
+Routes need a home that does not grow linearly in a central composition root.
+
+## Decision
+
+Routes are declared with method-specific PHP attributes (`Get`, `Post`, `Put`,
+`Patch`, `Delete`) on controller methods. A reflection-based `RouteLoader`
+compiles them into `RouteDef` objects. `Middleware` is a repeatable attribute
+valid on classes and methods.
+
+Matching precedence is deterministic: literal segments sort before
+`{parameter}` segments, so registration order is irrelevant.
+
+## Consequences
+
+- Adding a route touches only the controller.
+- The loader must be covered by tests (reflection is where mistakes hide).
+- Precedence is explicit rather than dependent on registration order.
diff --git a/docs/adr/0003-request-response-boundary.md b/docs/adr/0003-request-response-boundary.md
new file mode 100644
index 0000000..9129c0d
--- /dev/null
+++ b/docs/adr/0003-request-response-boundary.md
@@ -0,0 +1,27 @@
+# ADR 0003: Thin HTTP Contracts
+
+- Status: Accepted
+- Date: 2026-08-17
+
+## Context
+
+The kernel needs request/response types, but applications already have their
+own concrete HTTP objects (and their own security headers, session handling,
+and parsing).
+
+## Decision
+
+The kernel defines `RequestInterface` and `ResponseInterface` with only the
+surface routing needs (method, path, params) and middleware needs (headers).
+Applications implement these interfaces on their own classes.
+
+Middleware and controllers operate on the interfaces, so application code that
+needs app-specific features narrows to its concrete types.
+
+## Consequences
+
+- The kernel stays decoupled from any one app's HTTP layer.
+- Applications must implement the two interfaces (usually a small change to
+  existing Request/Response classes).
+- Middleware parameters use `RequestInterface`; concrete middleware may need
+  an `instanceof` narrowing to access app-specific request methods.
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 0000000..59eb6c9
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,50 @@
+# v0.1.0 Roadmap
+
+Initial release of the routing/middleware kernel.
+
+## Proposed beads
+
+### [EPIC] miniroute v0.1.0 — attribute routing + middleware kernel
+
+- Type: epic
+- Priority: P2
+
+Children (create with `--parent`):
+
+1. **Core: attribute route declaration and reflection loader**
+   - Type: task, Priority: P2
+   - Description: Implement `Get`/`Post`/`Put`/`Patch`/`Delete`/`Middleware`
+     attributes and `RouteLoader` reflection scanning.
+   - Acceptance: `RouteLoaderTest` passes.
+
+2. **Core: deterministic route matching**
+   - Type: task, Priority: P2
+   - Description: `RouteMatcher` with `{param}` support and
+     literal-before-parameter precedence.
+   - Acceptance: `RouteMatcherTest` passes.
+
+3. **Core: middleware pipeline and groups**
+   - Type: task, Priority: P2
+   - Description: `MiddlewarePipeline` onion composition and router-level
+     `group()` prefix middleware.
+   - Acceptance: `MiddlewarePipelineTest` and router group coverage pass.
+
+4. **Core: controller resolution and dispatch**
+   - Type: task, Priority: P2
+   - Description: `ControllerResolverInterface` seam and `Router::dispatch`.
+   - Acceptance: `RouterTest` passes.
+
+5. **Tests: unit coverage for loader/matcher/pipeline/router**
+   - Type: task, Priority: P2
+   - Acceptance: `vendor/bin/phpunit` green.
+
+6. **Docs: ADRs, README, usage**
+   - Type: task, Priority: P2
+
+7. **Release: Composer metadata and git tags**
+   - Type: task, Priority: P2
+   - Description: `composer.json` PSR-4 autoload, MIT license, tag `v0.1.0`.
+
+8. **Repo: publish to src.brett-parson.com**
+   - Type: task, Priority: P2
+   - Description: Add cgit remote, push, set `git-daemon-export-ok` marker.