Chore/claude encode session lessons

[emeraldleaf]

What changed

How it was built

Verification

Touches (check only if applies)

• EF Core migration (immutable once applied — see CLAUDE.md "Performance Rules")
• CLAUDE.md or a See CLAUDE.md paraphrase (run /check-rules to audit drift)

Summary by CodeRabbit

• Documentation
  • Enhanced security guidance with authorization patterns, JWT validation requirements, and IDOR prevention protocols.
  • Expanded testing requirements for authorization scoping and event persistence.
  • Clarified observability standards for trace ID formatting and HTTP middleware ordering.
  • Added continuous rule encoding workflow documenting how findings translate into persistent guidelines.
  • Updated AI agent documentation with pattern checklists and enhanced code review instructions.

[coderabbitai]

Walkthrough

This PR establishes a continuous feedback loop for encoding architectural patterns across documentation (CLAUDE.md), code review configuration (.coderabbit.yaml), agent prompts, and developer workflow docs. It introduces security patterns for IDOR prevention, explicit JWT validation, HTTP middleware ordering, and outbox atomicity, plus prescriptive checklists in the architecture-reviewer agent and rule-encoding guidance in CodeRabbit.

Changes

Architectural Rule Encoding Infrastructure

Layer / File(s)	Summary
Core architectural patterns and requirements CLAUDE.md	Security Requirements now mandate authorization-by-owner (handler returns null, endpoint maps to 404 for IDOR), explicit JWT validation (ValidateIssuerSigningKey, ClockSkew=30s), and strict trace ID handling (Activity.TraceId.ToString()). Testing Requirements add two integration tests: IDOR cross-buyer denial and outbox envelope persistence for non-Wolverine event publishing. HTTP middleware order (UseExceptionHandler → UseAuthentication → CorrelationIdMiddleware → UseAuthorization) and outbox atomicity patterns document when envelopes persist and prevent silent-drop failures.
Rule encoding infrastructure and workflow .claude/README.md, CLAUDE.md	.claude/README.md documents the directory structure, extension surfaces (agents, commands, skills), and guidance on where to encode patterns. CLAUDE.md's new "Continuous Rule Encoding" section describes the multi-surface workflow: encode findings across CLAUDE.md, CodeRabbit paths, agent checklists, and docs, coupling rule updates with fix PRs.
Architecture reviewer agent pattern detection .claude/agents/architecture-reviewer.md	Agent now explicitly references CLAUDE.md Security, Observability, and Testing sections. "Pattern checklist" adds domain-specific auditable checks for HTTP endpoints (IDOR, mass-assignment, pagination), recovery jobs (outbox ordering, DI scope, distributed locking), ServiceDefaults (middleware, JWT params, trace ID), query handlers (tracking, pagination, N+1), aggregates (state transitions, immutability), and GitHub workflows (bash safety, permissions). A "Rules to encode" output section prompts reviewers to name patterns and propose rule wording.
CodeRabbit path-specific review guidance .coderabbit.yaml	Path instructions enforce IDOR prevention (scope checks, 404 vs 403, endpoint template references), recovery/background job atomicity (SaveChangesAsync before transaction commit, DI scope per iteration), and ServiceDefaults hardening (middleware ordering, JWT validation parameters, trace ID format, unit-test coverage requirement).
Developer feedback loop documentation docs/dev-loop.md	"Continuous Rule Encoding" section explains how PR-time CodeRabbit feedback, agent runs, test failures, and incidents flow into persistent rule encodings across the repository, with the architecture-reviewer agent driving prompts so fixes and encodings land together.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• emeraldleaf/NextAurora#24: Updates to .coderabbit.yaml path instructions for GitHub workflow review conventions are related to this PR's additional security and infrastructure reviews.path_instructions rules added to the same CodeRabbit configuration surface.
• emeraldleaf/NextAurora#25: Documents the same security trio specifics as PR #25—CorrelationIdMiddleware ordering, JWT TokenValidationParameters configuration, and GlobalExceptionHandler using Activity.TraceId.ToString()—so the documentation changes encode the patterns from that code/test work.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Chore/claude encode session lessons' is vague and uses non-descriptive terms that obscure the actual changes, making it unclear to someone scanning history what the PR accomplishes.	Revise to be more specific and clear, such as 'Document continuous rule encoding workflow and security patterns' or similar, to better convey the substantive documentation additions.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/claude-encode-session-lessons

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CLAUDE.md`:
- Around line 31-46: CLAUDE.md changed security rules (owner-scoped
authorization pattern, explicit TokenValidationParameters, traceId usage,
validators, etc.), so run the local audit command (/check-rules) and update
every paraphrase that ends with "See CLAUDE.md" to reflect the new specifics:
ensure references to the owner-check pattern mention ClaimTypes.NameIdentifier →
RequestingBuyerId flow and the handler-return-null → endpoint-404 behavior (see
OrderEndpoints.cs/ShippingEndpoints.cs/CatalogEndpoints.cs examples), require
FluentValidation for commands, update AddDefaultAuthentication /
TokenValidationParameters to set ValidateIssuerSigningKey=true,
ValidateAudience/ValidateIssuer/ValidateLifetime=true and
ClockSkew=TimeSpan.FromSeconds(30), and change guidance to use
Activity.TraceId.ToString() (not Activity.Id) per GlobalExceptionHandler.cs;
search the repo for "See CLAUDE.md" and repair each paraphrase to match these
exact requirements.
- Around line 283-296: The fenced C# snippet for ExecuteInTransactionAsync is
missing blank lines before and after the triple-backtick fences; add a blank
line immediately above the opening ```csharp and a blank line immediately below
the closing ``` so the fenced code block is separated from surrounding
paragraphs (adjust the block containing ExecuteInTransactionAsync accordingly to
satisfy MD031).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b2f67a7f-7ec4-48c3-bdd1-0b8e33cb2041

📥 Commits

Reviewing files that changed from the base of the PR and between 0dca379 and e54ac9e.

⛔ Files ignored due to path filters (1)

• docs/dev-loop.svg is excluded by !**/*.svg

📒 Files selected for processing (5)

• .claude/README.md
• .claude/agents/architecture-reviewer.md
• .coderabbit.yaml
• CLAUDE.md
• docs/dev-loop.md

minor document issue