🏛️ Codify capability-backed policy middleware as an architecture pattern

[taras]

Story

As a contributor designing an extensible execution boundary, I want the repository's capability-backed policy-middleware pattern documented and reviewable, so replaceable middleware is not accidentally given authority over execution, durable state, lifecycle, or authoritative outcomes.

Motivation

The same design has emerged across several structural boundaries:

• ExecutionRequest lets public middleware inspect, narrow, refuse, and delegate while canonical core owns execution and settlement.
• DocumentRequest lets middleware surround document execution without substituting its authoritative outcome.
• Workspace coordination lets contextual policy select or refuse a provider while an execution-owned credentialed capability owns execution and publication.
• A bound foreground command must derive its outcome from the canonical process boundary rather than from replaceable modifier middleware.

Recent implementation feedback exposed the same mistake in two forms: classifying authority by the replaceable string "timeout", and carrying an authoritative fact through the public applyModifiers return value. Both would have been caught by asking whether a name, registry entry, context value, or middleware result was being treated as authority.

The architecture already states that public middleware is non-authoritative by construction, but the reusable design and its review questions are distributed across individual mechanisms.

Pattern to document

For an operation with a structural consequence:

execution owner
 issues an opaque, one-use request
 ↓
public middleware
 observes / narrows / refuses / delegates
 ↓
private terminal
 validates the exact request and records acceptance
 ↓
execution owner
 performs the authoritative work and publishes its result

Public middleware may stop an operation or add a failure. Delegation and a middleware return value do not authorize execution, manufacture completion, substitute the authoritative result, or recover an outcome owned elsewhere.

This is a pattern for structural authority boundaries, not a claim that all middleware is non-behavioral. Formatting, display routing, configured host preprocessing, and ordinary language-level transformations retain their documented semantics.

Scope

• Give the pattern one repository term, preferably capability-backed policy middleware, and define it in architecture.md.
• Inventory the existing instances and explain their meaningful differences, including whether middleware unwinds before work, surrounds work, or selects a provider across a transaction boundary.
• Add a concise design and review checklist to the appropriate Architect, Planner, and Implementor guidance.
• Link the task-oriented documentation index from Add an entrypoint to the README for finding documentation, code, and tests for a change #450 to this pattern when that index exists.

The checklist should ask at least:

• What structural consequence is being protected?
• Who owns authoritative execution and settlement?
• What may middleware observe, narrow, replace, or refuse?
• May middleware short-circuit, and what does that mean?
• Can a middleware return value substitute authoritative completion?
• How is delegation tied to one invocation and refused when stale, copied, reused, or fabricated?
• Does any stable name, Context value, registry entry, structural object, or loaded-copy convention accidentally confer authority?
• How are failures before delegation, during canonical work, and after authoritative completion ranked?
• Which behavior is intentionally ordinary middleware rather than part of this authority pattern?

Acceptance

• The architecture defines the pattern without changing the settled behavior of its existing instances.
• Existing instances are linked to the shared doctrine instead of independently restating its core authority rule.
• Role guidance contains a short, actionable replaceable-authority review checklist.
• At least one example shows the prohibited shape: accepting a name or public middleware result as proof of authoritative execution.
• The documentation distinguishes policy middleware from intentionally behavioral middleware clearly enough that contributors do not apply the restriction indiscriminately.

Not this issue

• Creating a generic request or capability framework.
• Refactoring existing implementations solely to make their mechanics look alike.
• Changing foreground-output preprocessing, modifier composition, or provider behavior.

A shared implementation abstraction should wait until multiple consumers share mechanics as well as principles.

[taras]

The architecture pattern and its remaining role-specific review checklist are now consolidated into #491. That story owns the repository-wide scope and middleware audit, the shared ownership model, static/test/review enforcement classification, and the Architect, Planner, and Implementor checklist.

Closing this narrower documentation story as superseded by #491.