Skip to content

docs(structural): meta-docs sync per holistic critique#32

Merged
mghabin merged 1 commit into
mainfrom
struct/meta-docs
Apr 30, 2026
Merged

docs(structural): meta-docs sync per holistic critique#32
mghabin merged 1 commit into
mainfrom
struct/meta-docs

Conversation

@mghabin

@mghabin mghabin commented Apr 30, 2026

Copy link
Copy Markdown
Owner

Applies the META-DOCS findings from the holistic critique (holistic.critique.json).

Per-file changes

README.md

  • Baseline corrected: .NET 10 / C# 14 / Aspire (with explicit split: Aspire 9.x for net8/9 services, Aspire 13 for net10 services; rebrand to 'Aspire' / aspire.dev noted).
  • Advertised decision-tree list rewritten to match the actual docs/decision-trees.md set (now 17 trees, including Aspire scope and Cosmos partition key — added in this PR).
  • Chapter blurbs updated: ch01 says C# 14, ch02 says 'separate delegated and app-only policies' (mirrors §10), ch06 says Aspire 9.x/13 split.

SCOPE.md

  • C# 14 baseline (with link to whats-new/csharp-14 + the configure-language-version doc that explains TFM-driven defaults).
  • Aspire baseline restated as the 9.x / 13 split.
  • Reading paths (§6.1/6.2/6.3) now start with docs/decision-trees.md, matching README's positioning of decision-trees as the synthesis entrypoint.

glossary.md

Added (alphabetically, with Source: lines pointing at primary sources):

  • DistributedApplicationTestingBuilder (Aspire testing host)
  • dotnet-affected (monorepo CI fan-out)
  • Federated Identity Credentials (Entra → external OIDC issuers)
  • RequiredScope (Microsoft.Identity.Web attribute, ch02 §10)
  • slnx (.NET 9 solution format) (the XML solution format)
  • Traversal SDK (Microsoft.Build.Traversal)
  • Workload Identity (AKS keyless workload-auth)

coverage-map.md

  • ch02 ownership expanded: HttpClient (§11), OutputCache (§9), BackgroundWork (§12), Security (§14), gRPC (§16), SignalR (§17), HealthChecks endpoint mapping (§18, with explicit note that ch06 §10 owns the probe contract). Auth section (§10) now states 'separate delegated and app-only policies'. Resilience (§7) named as single owner with ch06 referencing it.
  • ch06 ownership expanded: Configuration (§4), Resilience pipeline (§6, non-HTTP), HealthChecks probe contract (§10 — owns endpoint names + semantics), GracefulShutdown (§11), CI/CD (§12), Networking (§13), Multi-tenancy (§14), Cost (§15). Aspire entry restated as 9.x/13 split.
  • Checklist block weakened from 'every line links to its owning chapter' to an accurate description of the footer chapter index, matching what checklist.md actually does.

docs/decision-trees.md

  • Tree 12 (Auth) rewritten to mirror ch02 §10 — two separate named policies (delegated requires scp; app-only requires roles + azp allow-list + absence of scp), composed at the endpoint via RequireAuthorization('Delegated','App'). The previous 'combined OR-claims policy' branch (which ch02 explicitly rejects as a privilege-escalation bug) is gone.
  • Tree 15 (Resilience) points to single owner ch02 §7 (docs/02-aspnetcore.md#7-resilience); ch06 references that section, doesn't co-own it. Hedging branch now uses AddStandardHedgingHandler.
  • All other trees: References: lines converted from file-level links to section-anchor links.
  • Tree 16 (Aspire scope) added: Aspire.Hosting.* belongs in the AppHost project only; Aspire.<Vendor>.<Tech> client integrations belong in the service project. Routes to ch06 §1.
  • Tree 17 (Cosmos partition key) added: high-cardinality + on-the-dominant-read-path + write-distributed; if two read patterns conflict, fan out via change feed to a second container. Routes to ch03 §1 / §8.

patterns/anti-patterns.md

  • 'God csproj' fix is now architecture-neutral: vertical slice (Bogard), clean/onion (Ardalis), and modular monolith (Grzybek) are all valid endpoints. The rule is split at bounded-context seams, with the host as the only infra-referencing project — not 'use Clean Architecture'.

Style

  • - bullets, primary-source URLs on every new normative claim, one sentence per line in new prose, no heading skips.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

- README/SCOPE: update baseline to .NET 10 / C# 14 / Aspire 9.x (net8/9) +
  Aspire 13 (net10), refresh advertised decision-tree list, route reading
  paths through decision-trees.md first.
- glossary: add RequiredScope, DistributedApplicationTestingBuilder,
  Workload Identity, Federated Identity Credentials, slnx, Traversal SDK,
  dotnet-affected with primary-source citations.
- coverage-map: name owners for ch02 sections (HttpClient, OutputCache,
  BackgroundWork, Security, gRPC, SignalR, HealthChecks endpoint mapping)
  and ch06 sections (Configuration, Resilience, HealthChecks probe contract,
  GracefulShutdown, CI/CD, Networking, Multi-tenancy, Cost). Weaken the
  per-line checklist deep-link claim to match reality (footer chapter list).
- decision-trees: rewrite tree 12 (auth) to mirror ch02 §10 — separate
  delegated and app-only policies, no single OR-claims policy. Point tree
  15 (resilience) at single owner ch02 §7. Convert all References lines to
  section anchors. Add tree 16 (Aspire scope: AppHost vs service) and tree
  17 (Cosmos partition key) so the README list is honest.
- patterns/anti-patterns: make 'God csproj' fix architecture-neutral —
  vertical slice, clean/onion, modular monolith all valid; rule is split
  at bounded-context seams with host as the only infra-referencing project.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@mghabin mghabin merged commit e2a56c8 into main Apr 30, 2026
3 checks passed
@mghabin mghabin deleted the struct/meta-docs branch April 30, 2026 15:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant