docs(mediator): reorganize tracking docs and design release-scope tasks

[Copilot]

Documentation-only change. Reviews the executed mediator-framework work, realigns design.md with what shipped, separates delivery tracking from reference documentation, and specifies the seven remaining release-required features as executable task documents.

Docs reorganization

• All progress/tracking moved into docs/mediator-framework/progress/: tasks.md, implementation-plan.md, pre-release-review.md, future-improvements.md, tasks/, plus a new progress/README.md index stating the working agreement (per-task PR, build/test gates, design updates).
• docs/mediator-framework/ now holds reference material only: design.md, research.md, migration-from-mvc.md.
• Links updated in the docs index and samples/Ark.MediatorFramework.Sample/README.md.

Design document alignment

• Corrected drift: the HTTP error section still described Hellang.Middleware.ProblemDetails; the shipped path is the shared Ark.Tools.AspNetCore.ProblemDetails IExceptionHandler (AddArkProblemDetailsExceptionHandler / UseArkProblemDetailsExceptionHandler) with the actual mapping table (403/404/409/412/501/503).
• New sections specifying the pending scope: standard error responses, OpenAPI grouping/naming/XML documentation, IAsyncEnumerable<T> streaming responses, multi-file uploads, API surface snapshots, and the user guide.

Executed-work review

Epics 1–11 and task board items SEC-01..08, FW-01..04, GEN-01..08, SMP-01..03 accepted as correct. Pre-existing pending blockers unchanged: SMP-04, SMP-05, SMP-06, NET-01.

New release-required tasks (decision D8, Epic 12 / Phase 10)

Task	Substance
NET-06	Tag defaults to contract namespace, operationId to class name; [ApiTag] override in the core package; gRPC grouping falls back to the same value; duplicate-name diagnostic
GEN-09	Generators read ISymbol.GetDocumentationCommentXml() → operation/parameter/schema descriptions and .proto leading comments; no per-host wiring, no runtime XML files. Supersedes NET-01's XML step (NET-01 rescoped to 3.1 verification, YAML, doc-UI decision)
FW-05	400/403/500 application/problem+json on every generated endpoint kind, proven by a test that enumerates all operations of all documents
FW-06	Streaming JSON array on Minimal API, server-streaming gRPC, MessagePack buffered (the format requires the element count in the array header) bounded by MaxStreamedItems; Rebus + streaming is a diagnostic; no SSE
FW-07	One attachment member may be a collection; MaxFileCount plus per-file content-type/filename hardening; gRPC stream delimits files by metadata message
GEN-10	PublicApiAnalyzers-style shipped/unshipped snapshot, but over the transport surface (routes, params, policy, operationId, gRPC methods/field numbers/streaming kind, Rebus queues); ARKAPI001-003 + code fix so wire changes appear as a reviewable diff
DOC-01	docs/mediator-framework/guide/: getting started + one page per feature, snippets cited from compiled sample code

Snapshot entry format proposed by GEN-10:

HTTP GET /api/v1/greetings/{id} -> GetGreetingQuery : GreetingDto [policy=RequireAuthenticatedUser] [op=GetGreetingQuery] [tag=Greetings]
GRPC Greetings.V1/GetGreeting (GetGreetingQuery) returns (GreetingDto) unary
GRPC-FIELD GetGreetingQuery.Id = 1 : bytes
REBUS RefreshGreetingCommand -> queue:greetings

Each task document carries problem, design, step-by-step guide with framework documentation links, a mandatory test-coverage section, and an acceptance checklist ending in the full-solution build and test gates. Ordering is deliberate: wire-shape items first, the API-surface gate after them so the first committed snapshot is the release surface, documentation last.

Tracking updates

Decision D8 recorded in pre-release-review.md; Epic 12 added to tasks.md; Phase 10 added to implementation-plan.md; task board gains the new blockers and an updated execution order.

[Copilot]

Pull request overview

Reorganizes the mediator-framework documentation to separate delivery tracking from reference docs, updates cross-links accordingly, and expands the tracking/task system to cover the remaining release-scope items (Decision D8) while updating design.md to reflect shipped behavior and the agreed next scope.

Changes:

• Move delivery tracking docs under docs/mediator-framework/progress/ and update links in the docs index and sample README.
• Rescope and (re)introduce task documents under progress/tasks/, including D8’s seven new release blockers, plus an index and working agreement.
• Update design.md with shipped ProblemDetails wiring and new sections for pending release-scope features.

Reviewed changes

Copilot reviewed 17 out of 48 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
samples/Ark.MediatorFramework.Sample/README.md	Updates links to the relocated progress/tracking docs and removes the stale Hellang mention.
docs/mediator-framework/tasks/aspnetcore/NET-01-openapi-xml-docs.md	Removes old NET-01 task doc from the pre-reorg location.
docs/mediator-framework/README.md	Splits reference vs tracking documents and points tracking to progress/.
docs/mediator-framework/progress/tasks/security/SEC-08-test-auth-bearer-hardening.md	Adds task spec for malformed bearer handling in test auth.
docs/mediator-framework/progress/tasks/security/SEC-07-error-serialization-hardening.md	Adds task spec for opt-in error detail serialization + exception message hardening.
docs/mediator-framework/progress/tasks/security/SEC-06-multipart-hardening.md	Adds task spec for multipart hardening (antiforgery posture, limits, filename sanitization).
docs/mediator-framework/progress/tasks/security/SEC-05-transport-agnostic-authorization-decorator.md	Adds task spec for a policy decorator covering HTTP/gRPC/Rebus uniformly.
docs/mediator-framework/progress/tasks/security/SEC-04-server-set-binding-protection.md	Adds task spec for [ServerSet] to prevent mass assignment across transports.
docs/mediator-framework/progress/tasks/security/SEC-03-messagepack-untrusted-data.md	Adds task spec for MessagePack UntrustedData and startup formatter validation.
docs/mediator-framework/progress/tasks/security/SEC-02-unconditional-authorization-middleware.md	Adds task spec to remove conditional UseAuthorization gating in the sample.
docs/mediator-framework/progress/tasks/security/SEC-01-secure-by-default-endpoints.md	Adds task spec for secure-by-default endpoint emission and per-endpoint policy support.
docs/mediator-framework/progress/tasks/sample-parity/SMP-06-misc-parity.md	Adds/records remaining sample parity work (AI/config layering/IClock/test infra).
docs/mediator-framework/progress/tasks/sample-parity/SMP-05-paging.md	Adds/records paging parity task.
docs/mediator-framework/progress/tasks/sample-parity/SMP-04-optimistic-concurrency.md	Adds/records optimistic concurrency parity task.
docs/mediator-framework/progress/tasks/sample-parity/SMP-03-persisted-auditing.md	Adds/records persisted auditing parity task.
docs/mediator-framework/progress/tasks/sample-parity/SMP-02-sql-dapper-outbox.md	Adds/records SQL persistence + outbox parity task.
docs/mediator-framework/progress/tasks/sample-parity/SMP-01-fluentvalidation.md	Adds/records FluentValidation decorator pattern task.
docs/mediator-framework/progress/tasks/README.md	Updates task board index and adds D8 scope-extension section + execution order.
docs/mediator-framework/progress/tasks/generator-dx/GEN-10-api-surface-snapshots.md	Adds task spec for transport API surface snapshots + analyzer/code fix.
docs/mediator-framework/progress/tasks/generator-dx/GEN-09-xml-documentation.md	Adds task spec for generator-driven XML docs into OpenAPI and exported protos.
docs/mediator-framework/progress/tasks/generator-dx/GEN-08-from-assembly-api-names.md	Adds task spec documenting the assembly-scanning API naming change.
docs/mediator-framework/progress/tasks/generator-dx/GEN-07-automatic-proto-export.md	Adds task spec for build-time proto export without running host entry points.
docs/mediator-framework/progress/tasks/generator-dx/GEN-06-grpc-user-context-interceptor.md	Records the cancelled user-context interceptor work with rationale.
docs/mediator-framework/progress/tasks/generator-dx/GEN-05-rebus-cancellation-token.md	Adds/records Rebus cancellation token flow task.
docs/mediator-framework/progress/tasks/generator-dx/GEN-04-remove-hardcoded-documents-proto.md	Adds/records task to remove sample proto leakage from framework generator.
docs/mediator-framework/progress/tasks/generator-dx/GEN-03-startup-handler-verification.md	Adds/records startup handler verification task.
docs/mediator-framework/progress/tasks/generator-dx/GEN-02-diagnostics-for-silent-failures.md	Adds/records generator diagnostics catalog task.
docs/mediator-framework/progress/tasks/generator-dx/GEN-01-incremental-generators.md	Adds/records incremental generator pipeline task.
docs/mediator-framework/progress/tasks/framework/FW-07-multifile-uploads.md	Adds task spec for multi-file upload binding + gRPC streaming delimited files.
docs/mediator-framework/progress/tasks/framework/FW-06-async-enumerable-streaming.md	Adds task spec for IAsyncEnumerable<T> streaming on HTTP/gRPC and buffered MessagePack.
docs/mediator-framework/progress/tasks/framework/FW-05-standard-problem-responses.md	Adds task spec for standard 400/403/500 ProblemDetails response metadata everywhere.
docs/mediator-framework/progress/tasks/framework/FW-04-file-download.md	Adds/records file-download support task.
docs/mediator-framework/progress/tasks/framework/FW-03-shared-problemdetails-package.md	Adds/records shared ProblemDetails extraction task.
docs/mediator-framework/progress/tasks/framework/FW-02-http-status-semantics.md	Adds/records HTTP status semantics task.
docs/mediator-framework/progress/tasks/framework/FW-01-icommand-support.md	Adds/records ICommand support task across transports.
docs/mediator-framework/progress/tasks/docs/DOC-01-user-documentation.md	Adds task spec for end-user guide structure and link/snippet discipline.
docs/mediator-framework/progress/tasks/aspnetcore/NET-06-openapi-tags-operation-names.md	Adds task spec for tag/operationId defaults + [ApiTag] and diagnostics.
docs/mediator-framework/progress/tasks/aspnetcore/NET-05-sse-transport-spike.md	Adds post-release spike task for SSE transport exploration.
docs/mediator-framework/progress/tasks/aspnetcore/NET-04-auth-metrics.md	Adds post-release task for auth/identity metrics collection/documentation.
docs/mediator-framework/progress/tasks/aspnetcore/NET-03-json-patch.md	Adds post-release task for PATCH support via STJ JSON Patch.
docs/mediator-framework/progress/tasks/aspnetcore/NET-02-openapi-operation-transformers.md	Adds post-release task for per-endpoint OpenAPI transformers.
docs/mediator-framework/progress/tasks/aspnetcore/NET-01-openapi-xml-docs.md	Adds rescoped NET-01 task (3.1 verification, YAML endpoint, doc-UI decision).
docs/mediator-framework/progress/tasks.md	Adds Epic 12 (D8 scope extension) and updates next implementation order text.
docs/mediator-framework/progress/README.md	Adds a tracking index + working agreement for per-task PR execution.
docs/mediator-framework/progress/pre-release-review.md	Records Decision D8 and updates priority ordering accordingly.
docs/mediator-framework/progress/implementation-plan.md	Adds Phase 10 describing Epic 12 execution order and gating.
docs/mediator-framework/progress/future-improvements.md	Adds post-1.0 future improvements list linked from decisions.
docs/mediator-framework/design.md	Updates ProblemDetails wiring description and adds new sections for pending scope items.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AndreaCuneo]

it's also needed that CI/CD fails if the API surface changed without explicit manual acceptance. Add a standard analyzer to avoid Releasing with changes to contract.
@copilot

[Copilot]

Done. Added ARKAPI004 (error) that fires when $(ArkApiSurfaceEnforceRelease) is true and ArkApiSurface.Unshipped.txt is non-empty — CI/CD pack/release jobs set this flag and fail until the developer explicitly promotes changes to Shipped.txt.

Changes in commit docs(mediator): add ARKAPI004 CI/CD release gate to GEN-10 and design.md:

• design.md: new Release gate paragraph in the API surface snapshots section.
• GEN-10-api-surface-snapshots.md: ARKAPI004 added to the diagnostics table; step 5 specifying how to wire the flag in CI; test cases for the gate; Outcomes and Acceptance updated.

[AndreaCuneo]

the approach is too cumbersome to be generated manually.
redesign it again with the following Rules:

• API surface file is generated automatically as comparison
• the snapshot can be accepted by dev by copying the generated file onto the snapshot and commit it
• the api surface must detect changes to nested fields

outcomes: the developers only have to update the Snapshot file by copying from the framework-generated one as "confirming" the intent to impact the API. if they don't the build fails. if the snapshot file doesn't exists, build fails. the snapshot file guarantees ordering to ensure smooth diffs.

@copilot

[Copilot]

Redesigned in commit docs(mediator): redesign GEN-10 to single-snapshot copy-replace workflow.

New design — single ArkApiSurface.txt:

• Generator writes the current surface to obj/ArkApiSurface.current.txt on every build.
• MSBuild target compares it with the committed ArkApiSurface.txt; fails with ARKAPI001 (missing) or ARKAPI002 (differs).
• Developer accepts by cp obj/.../ArkApiSurface.current.txt ArkApiSurface.txt && git add; no manual editing, no shipped/unshipped split.
• Nested fields are expanded recursively (CONTRACT Outer.Inner.Field : type, CONTRACT Items[].Field : type) so any rename anywhere in the contract graph produces a visible diff.
• CI gate is automatic at every stage — no separate release flag needed.