Merge pull request #268 from TimeWarpEngineering/dev

Agent context regions: skill extraction, AGENTS.md maintenance rule, 160-file backfill (050-010)

Author: StevenTCramer

AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+Guidance for all coding agents working in this repository (included by CLAUDE.md).
+
+## Agent Context Regions — maintenance rule
+
+Non-trivial source files carry embedded context regions (`#region Purpose`, `#region Design`,
+optionally `#region Open Questions`). These are part of the code, not decoration:
+
+- **When you edit a file that has regions, reconcile them with your change before finishing.**
+  A Design region describing the old approach is a bug you just introduced.
+- **When you create a non-trivial source file, add `Purpose` and `Design` regions** at the top,
+  before the namespace.
+- **When you read an unanswered question in `#region Open Questions` that you can answer,**
+  answer it (or implement the answer and remove the pair).
+
+Formats, lifecycle, and what counts as trivial: see the `agent-context-regions` skill.

CLAUDE.md

@@ -2,6 +2,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+@AGENTS.md
+
 ## Repository Structure
 
 This is a **multi-project repository** containing .NET project templates and supporting infrastructure:

kanban/done/050-010-add-region-purpose-and-region-design-to-all-migrated-source-files.md

@@ -0,0 +1,66 @@
+# Add #region Purpose and #region Design to all migrated source files
+
+## Parent
+050-establish-root-directory-structure-source-tests-in-kebab-case
+
+## Summary
+
+All 050-x migration subtasks are complete; this is the deferred backfill pass. Add
+`#region Purpose` and `#region Design` blocks to every non-trivial .cs file under `source/`, per
+the **agent-context-regions** skill. Deferred until after migration so regions are written with
+full architectural context.
+
+Adoption at task start: **4 of 304** .cs files have `#region Purpose`; 0 have `#region Design`.
+
+## Scope
+
+All .cs files under `source/`:
+- `source/foundation/` (foundation-contracts, -contracts-generators, -domain, -application,
+  -infrastructure, -server)
+- `source/libraries/` (timewarp-modules)
+- `source/analyzers/` (timewarp-architecture-attributes, -analyzers, -contract-analyzers)
+- `source/container-apps/` (web, api, grpc, aspire, yarp)
+
+## Skills
+
+- agent-context-regions (format, placement, maintenance rule, what counts as trivial)
+- csharp (surrounding style)
+
+## Checklist
+
+### Phase 1: Inventory
+- [x] Inventory: 168 non-trivial candidates (excluded markers, global-usings, generated, <12-line
+      files, and the 4 already done).
+- [x] Grouped path-ordered into 14 slices of ~12 files for project-affine context.
+
+### Phase 2: Add Regions
+- [x] 14-agent workflow backfilled **160 files** (commit `98c63180`; 1,861 insertions, **0 deletions**
+      — verified insertion-only via `git diff --numstat`).
+- [x] **8 skipped with recorded reasons**: dead commented-out entities (`category.cs`, `product.cs`),
+      `#if false` body (`user-claims-base.cs`), sub-threshold stubs (`greeter-service.cs`,
+      `SideNavigationLink.razor.cs`, `assembly-extensions.cs`), and files whose single design fact
+      was already an inline comment (`constants.cs`, `java-script-interop-constants.cs`).
+- [x] Rules enforced in agent prompts: why-not-what, no temporal language, insertion-only, ≤14 lines.
+
+### Phase 3: Verify
+- [x] `dev build` green (0/0) — regions coexist with source-generated partials.
+- [x] Random spot-checks carry genuine *why* (e.g. service-uri-provider: browser can't read Aspire
+      env vars → server exposes /service-discovery; policy-registration: explicit always-true
+      Anonymous policy avoids special-casing).
+
+## Result
+
+Region coverage went from 4/304 to 164/304 `.cs` files, with the remainder deliberately trivial.
+Freshness from here on is the `AGENTS.md` maintenance rule; presence enforcement via an analyzer
+remains a candidate follow-up (see Notes).
+
+## Notes
+
+- Ongoing freshness is covered by the maintenance rule in `AGENTS.md` (included by CLAUDE.md):
+  every edit reconciles the file's regions. This task is the one-time backfill.
+- Candidate follow-up (own task): a `TWPA` analyzer in `timewarp-architecture-contract-analyzers`
+  flagging non-trivial files without `#region Purpose` — presence enforcement, same lesson as the
+  nullability analyzer.
+
+## Session
+- Created: ses_2d78597cfffeIe36aerm1ibchw (2026-04-21)

kanban/to-do/050-010-add-region-purpose-and-region-design-to-all-migrated-source-files.md

@@ -1,3 +1,14 @@
+#region Purpose
+// Authoritative registry of the TWE diagnostic ID range for the [ApiEndpoint] generation contract.
+#endregion
+
+#region Design
+// Centralized so IDs stay unique and stable across the generator and its validators; an ID may
+// exist here without a referencing check — reserve the ID first, wire the enforcement separately.
+// All are Errors: a violated generation contract yields a missing or broken endpoint at runtime,
+// so it must fail the build instead.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 internal static class DiagnosticDescriptors

source/analyzers/timewarp-architecture-analyzers/diagnostics/diagnostic-descriptors.cs

@@ -1,3 +1,17 @@
+#region Purpose
+// Generates FastEndpoint classes from [ApiEndpoint] contract types in referenced assemblies.
+#endregion
+
+#region Design
+// Opt-in via the EnableApiEndpointGeneration MSBuild property (default false) so any project can
+// reference the analyzers package without silently emitting endpoints.
+// Scans referenced-assembly symbols rather than the current compilation's syntax: contracts live
+// in a separate project from the server that hosts the generated endpoints.
+// Reports SG002 instead of failing when FastEndpoints/BaseFastEndpoint are absent — feature flags
+// can strip those references while the generator package remains attached.
+// Catches all exceptions (CA1031): a throwing generator would break the entire compilation.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 using TimeWarp.Architecture.Analyzers.Models;

source/analyzers/timewarp-architecture-analyzers/generators/fast-endpoint-source-generator.cs

@@ -1,3 +1,12 @@
+#region Purpose
+// Case-convention conversions shared by the analyzers and generator.
+#endregion
+
+#region Design
+// ToKebabCase must mirror the repo's file-naming convention exactly — the partial-class file-name
+// analyzer derives expected file names from it, so a drift here changes what the analyzer accepts.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 using System.Globalization;

source/analyzers/timewarp-architecture-analyzers/helpers/string-extensions.cs

@@ -1,3 +1,16 @@
+#region Purpose
+// Extracts everything the FastEndpoint generator needs from an [ApiEndpoint] contract symbol.
+#endregion
+
+#region Design
+// One flat DTO decouples template emission from Roslyn symbol traversal, so the generated-code
+// template can change without touching symbol-walking logic.
+// OpenAPI summary/description come from the Query/Command XML docs — the contract is the single
+// authoring point for API documentation.
+// Tags default to the feature folder name (namespace segment above "Features"), keeping OpenAPI
+// grouping aligned with the vertical-slice layout without per-endpoint annotation.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers.Models;
 
 internal sealed class EndpointMetadata

source/analyzers/timewarp-architecture-analyzers/models/endpoint-metadata.cs

@@ -1,3 +1,17 @@
+#region Purpose
+// Enforces the primary/secondary file convention for multi-file partial classes (TWPA0001).
+#endregion
+
+#region Design
+// The convention keeps one authoritative declaration — modifiers and base class — in the file
+// named after the type; secondary files (Type.behavior.cs, e.g. state action partials) stay
+// minimal so declarations across partials can never disagree.
+// Both PascalCase and kebab-case file names are accepted: the repo convention is kebab-case, but
+// the standard .NET convention must also pass for consumers of the packaged analyzer.
+// Interface implementations are allowed in secondary files (the 'I'-prefix heuristic); only class
+// inheritance is restricted, so the type's ancestry is stated exactly once.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 [DiagnosticAnalyzer(LanguageNames.CSharp)]

source/analyzers/timewarp-architecture-analyzers/partial-class-declaration-analyzer.cs

@@ -1,3 +1,15 @@
+#region Purpose
+// Detects duplicate route+verb registrations across generated endpoints (TWE003).
+#endregion
+
+#region Design
+// Static because incremental-generator source outputs run per symbol with no shared pipeline
+// state; the generator resets it at Initialize so entries from a prior compilation cannot
+// produce false conflicts. ConcurrentDictionary guards parallel source-output invocations.
+// First registration wins — the conflicting endpoint is reported and simply not generated,
+// keeping the rest of the compilation usable.
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 internal sealed class RouteRegistry