From 8ffa3eb4d7842a9832e005ce33e33a5d2c8447dc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 13 Jul 2026 08:05:22 +0000
Subject: [PATCH 1/3] docs: add review guidelines and feedback routing for
 agents

Add AGENTS.md and code_review.md so an automated reviewer (Codex) follows a
single Conventional Comments specification, and the agent that fixes a pull
request routes disagreements and judgement calls to the human maintainer
instead of looping with the reviewer. Human merge stays the final gate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XAzVV5kTFuoTABDYZHSKR1
---
 AGENTS.md      | 123 +++++++++++++++
 code_review.md | 409 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 532 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 code_review.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f6fdab0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,123 @@
+# AGENTS.md — FirstClassErrors
+
+Instructions for automated agents (OpenAI Codex and others) in this repository.
+Two roles are covered: **writing code** and **reviewing pull requests**.
+
+## Project orientation (code changes)
+
+- .NET Standard 2.0 library. Errors are first-class, documented, diagnosable concepts.
+- Build: `dotnet build FirstClassErrors.sln`
+- Test: `dotnet test FirstClassErrors.sln` (analyzer tests: `dotnet test FirstClassErrors.Analyzers.UnitTests`).
+- Repository language is **English** (code, comments, commits, PRs, issues, and
+  review comments). French lives only in `doc/README.fr.md` and must stay in sync
+  with the English README.
+- `Error` and its hierarchy, `ErrorCode`, `ErrorContextKey`, `Outcome`/`Outcome<T>`
+  and any value object are **`class`, never `struct`** — a struct exposes a
+  zero-initialized default that bypasses validating constructors. Enums
+  (`Transience`, `ErrorOrigin`) are the only value-type exception.
+- Keep changes small and focused. Treat renamed error codes, diagnostic IDs and
+  public types as breaking changes.
+
+## Review guidelines (pull request reviews)
+
+READ THIS BEFORE REVIEWING. The full specification is in `code_review.md`; the
+rules below are mandatory and inlined so they are never missed.
+
+### Output format — mandatory
+
+Every inline comment MUST use exactly this shape, with nothing around it:
+
+```text
+<label> [(decorations)]: <subject on one line>
+
+<optional discussion>
+```
+
+- The entire comment is written in **English** — label, decorations, subject and
+  discussion. Code identifiers, API names and exception messages are quoted verbatim.
+- Never publish an unlabelled comment.
+- Exactly **one label** and **one independent finding** per comment. At most two decorations.
+- Do **NOT** add a severity/priority prefix — no `P0`, `P1`, `P2`, `P3`,
+  `critical`, `major`, `minor`, anywhere in the comment. Blocking status is
+  carried only by the label and the `(blocking)` / `(non-blocking)` decoration.
+- No introduction or conclusion around the comment. Place it on the smallest
+  relevant code range. Do not repeat the same finding on multiple lines.
+
+Canonical example:
+
+```text
+issue (security): The raw connection string is copied into the error context and reaches the logs.
+
+`ConnectionError.Create` stores the full connection string in the `ErrorContext`, and the
+log sink serializes every `Values` entry. The password therefore appears verbatim in any
+aggregated log output.
+
+Store only the host, or a redacted form, in the context — never the credential itself.
+```
+
+### Labels (one per comment)
+
+- `issue:` confirmed defect that must be addressed — *blocking*.
+- `todo:` small, obvious, local, non-debatable required change — *blocking*.
+- `chore:` mandatory process step before merge; name the command/file — *blocking*.
+- `question:` code looks suspicious but evidence is insufficient to assert a defect — *non-blocking*.
+- `suggestion:` concrete optional improvement (never for incorrect code — use `issue:`) — *non-blocking*.
+- `nitpick:` purely subjective, optional preference; should be rare — *non-blocking*.
+- `note:` relevant information, no change expected — *non-blocking*.
+- `thought:` design/architecture observation out of scope; must state no change is required here — *non-blocking*.
+- `praise:` genuinely good and worth preserving; explain what and why — *non-blocking*.
+
+Override a default only when the finding genuinely differs, e.g.
+`suggestion (blocking):` or `issue (non-blocking):`. Never restate a default
+(`issue (blocking):`, `nitpick (non-blocking):`).
+
+Allowed decorations: `(blocking)`, `(non-blocking)`, `(if-minor)`, `(security)`,
+`(perf)`, `(test)`, `(archi)`. One normally, never more than two.
+
+### What to report (priority order)
+
+Correctness → security → data integrity → regressions → public API / compatibility
+→ concurrency / reliability → significant performance → missing tests for a
+demonstrated risk → violations of an explicit repository rule (e.g. a value object
+converted to `struct`).
+
+Do NOT report: formatter-enforced style, analyzer-detected issues already flagged
+by an `FCExxx` rule, naming already enforced by tooling, speculative problems with
+no execution path, broad refactors unrelated to the PR, personal style presented as
+a requirement, or pre-existing issues the PR does not materially affect.
+
+If there is no relevant finding, approve without manufacturing comments.
+
+### Final summary
+
+Keep it concise. Report only: the number of blocking findings, the number of
+non-blocking findings, and the main risk areas. Do not restate every inline
+comment. If nothing was found, state clearly that no blocking issue was found.
+The summary is not a Conventional Comment and needs no label.
+
+## Responding to review feedback (acting agent)
+
+This section governs the agent that *fixes* a pull request in response to a
+review (for example `@claude`), not the reviewer. The human maintainer `@reefact`
+is the only authority that merges a pull request; no agent merges, and no agent
+enables auto-merge on its own pull request.
+
+For each review finding, take exactly one route:
+
+- **You agree and the fix is clear and local** — implement it, push, and reply on
+  the thread with `Resolved in <sha>`. You MAY ask the reviewer (`@codex`) for a
+  single confirming re-review; never open a back-and-forth.
+- **You believe the finding is wrong** — reply on the thread with the concrete
+  technical reason and mention `@reefact` to arbitrate. Do not ping `@codex` to
+  argue: a peer reviewer has no authority to settle the disagreement.
+- **The finding needs a human judgement** — architecture, a product trade-off, an
+  ambiguous requirement, a security or compatibility policy — mention `@reefact`
+  and wait. Do not decide unilaterally.
+
+Rules:
+
+- Never mention both `@codex` and `@reefact` on the same thread: a bot round-trip
+  or a human decision, never both.
+- At most two fix / re-review cycles per finding. If it is still open after that,
+  stop and mention `@reefact` instead of continuing.
+- Keep replies short and factual; the diff is the record.
diff --git a/code_review.md b/code_review.md
new file mode 100644
index 0000000..0fa6607
--- /dev/null
+++ b/code_review.md
@@ -0,0 +1,409 @@
+# Pull request review guidelines
+
+All pull request review comments must follow the Conventional Comments format
+described below. These instructions apply to automated Codex reviews.
+
+## Language
+
+* Every review comment is written in English: label, decorations, subject and discussion.
+* Code identifiers, API names, exception messages and other technical terms are
+  quoted verbatim in their original form.
+* Use a direct, factual and professional tone.
+* Do not use emojis.
+
+## Comment format
+
+Every inline review comment must use this format:
+
+```text
+<label> [(decorations)]: <subject>
+
+[discussion]
+```
+
+The subject must summarize the finding in one sentence.
+The optional discussion must explain:
+
+1. why the code is problematic;
+2. the concrete consequence;
+3. how the problem can be corrected, or at least a useful direction.
+
+Example:
+
+```text
+issue: This `Outcome` is discarded, so the failure it carries is silently lost.
+
+`Validate(order)` returns an `Outcome`, but the result is never inspected. When
+validation fails the caller keeps going as if it had succeeded, and the error is
+dropped instead of propagated.
+
+Capture the result and short-circuit on `IsFailure` (or chain with `Then`) so the
+error reaches the caller.
+```
+
+## General rules
+
+* Use exactly one label per comment.
+* Report exactly one independent finding per comment.
+* Use no more than two decorations.
+* Do not repeat the same finding on several lines of the diff.
+* Place the comment on the smallest relevant code range.
+* Do not write an introduction or conclusion around the formatted comment.
+* Do not include a severity or priority prefix such as `P0`, `P1`, `P2`, `P3`,
+  `critical`, `major` or `minor` anywhere in the comment. Blocking status is
+  expressed only through the label and the `(blocking)` / `(non-blocking)` decoration.
+* Do not comment on code that is outside the pull request unless the changed code
+  introduces or exposes the problem.
+* Do not comment on purely subjective preferences as though they were defects.
+* Do not invent a finding merely to produce a more complete-looking review.
+* If there are no relevant findings, approve the review without manufacturing comments.
+
+## Labels
+
+### `praise:`
+
+Use to highlight something specifically and genuinely successful.
+A praise comment must explain what is good and why it is worth preserving.
+Do not generate generic or complimentary filler.
+
+```text
+praise: The test names state the exact error condition they pin down.
+
+`Create_Throws_When_Code_Is_Whitespace` reads as the specification of
+`ErrorCode.Create`, so the guarded invariant is clear without opening the test body.
+```
+
+### `note:`
+
+Use to provide relevant information when no change or answer is expected.
+Do not use `note:` for a hidden request.
+
+### `thought:`
+
+Use for an architectural or design observation outside the scope of the pull request.
+The comment must explicitly state that no change is required in the current pull request.
+
+```text
+thought (archi): The Error-to-HTTP-status mapping is now duplicated across several endpoints.
+
+Nothing to change in this pull request. Centralizing the mapping could be a separate
+architecture decision if a third endpoint needs it.
+```
+
+### `question:`
+
+Use when the code appears suspicious but the available evidence is insufficient
+to assert that it is wrong.
+A question expects an explanation, not necessarily a code change.
+Do not disguise an assertion as a question.
+
+```text
+question: Is materializing `context.Values` with `.ToList()` before the `.Where()` intentional?
+
+It appears to copy every context entry before filtering on the key, which does more work
+than filtering first. If the goal is to snapshot the entries before a later mutation that
+is fine; otherwise the `.ToList()` can move after the filter.
+```
+
+When the defect is certain, use `issue:` instead.
+
+### `nitpick:`
+
+Use only for a clearly subjective and optional preference.
+The author must be free to ignore it.
+Do not use `nitpick:` for correctness, security, performance, compatibility,
+maintainability or architectural problems.
+Automated reviews should rarely produce nitpicks.
+
+### `suggestion:`
+
+Use to propose a concrete, non-mandatory improvement.
+State what should change and why the proposed form is better.
+Do not use `suggestion:` when the current implementation is actually incorrect.
+Use `issue:` instead.
+
+```text
+suggestion (test, if-minor): Add the case where the error context is empty.
+
+`ErrorContext.Empty` is a distinct boundary from a populated context. Add it here only
+if it does not require rebuilding the fixture.
+```
+
+### `chore:`
+
+Use for a mandatory process step that must happen before merge, such as:
+
+* updating a changelog;
+* regenerating committed artifacts (for example the generated error catalog);
+* updating version metadata;
+* running a required repository-specific operation.
+
+When possible, name the relevant command, file or documented procedure.
+`chore:` is blocking by default.
+
+### `todo:`
+
+Use for a mandatory change that is small, obvious, local and not reasonably open
+to debate.
+
+```text
+todo: Fix `occured` to `occurred` in the `NotFoundError` message.
+```
+
+Do not use `todo:` for a substantial defect or design problem. Use `issue:` instead.
+`todo:` is blocking by default.
+
+### `issue:`
+
+Use for a confirmed defect that must be addressed.
+Typical issues include:
+
+* incorrect behavior;
+* a regression;
+* data loss or corruption;
+* an unhandled failure;
+* a security vulnerability;
+* an invalid public API;
+* broken compatibility;
+* a race condition;
+* a meaningful performance regression;
+* a missing test that leaves a demonstrated regression unprotected;
+* a violation of an explicit repository invariant.
+
+An issue must include:
+
+1. the problematic behavior;
+2. the circumstances under which it occurs;
+3. its concrete impact;
+4. a correction or a useful direction toward one.
+
+Do not write vague comments such as:
+
+```text
+issue: This code is badly designed.
+```
+
+When the problem cannot be asserted confidently, use `question:`.
+`issue:` is blocking by default.
+
+## Decorations
+
+Decorations refine the label.
+Use a decoration only when it adds information not already implied by the label.
+Allowed decorations are:
+
+* `(blocking)` — must be resolved before merge;
+* `(non-blocking)` — must not prevent merge;
+* `(if-minor)` — perform only if the change remains trivial;
+* `(security)` — concerns security;
+* `(perf)` — concerns performance;
+* `(test)` — concerns test coverage or test quality;
+* `(archi)` — concerns architecture beyond the immediate scope of the pull request.
+
+Use one decoration in normal cases and never more than two.
+
+Correct:
+
+```text
+issue (security): The API key is copied into the error context and surfaces in the logs.
+```
+
+Correct:
+
+```text
+suggestion (test, if-minor): Add a case for the empty error context.
+```
+
+Incorrect:
+
+```text
+suggestion (test, perf, non-blocking, if-minor): ...
+```
+
+## Blocking rules
+
+The following labels are blocking by default:
+
+* `issue:`
+* `todo:`
+* `chore:`
+
+The following labels are non-blocking by default:
+
+* `praise:`
+* `note:`
+* `thought:`
+* `question:`
+* `nitpick:`
+* `suggestion:`
+
+An explicit blocking decoration overrides the default:
+
+```text
+suggestion (blocking): ...
+```
+
+An explicit non-blocking decoration also overrides the default:
+
+```text
+issue (non-blocking): ...
+```
+
+Do not add a decoration that merely repeats the default.
+
+Avoid:
+
+```text
+issue (blocking): ...
+nitpick (non-blocking): ...
+```
+
+Prefer:
+
+```text
+issue: ...
+nitpick: ...
+```
+
+Use an explicit override only when the finding genuinely differs from the default behavior.
+
+## Selecting findings
+
+Prioritize findings according to their actual impact:
+
+1. correctness;
+2. security;
+3. data integrity;
+4. regressions;
+5. public API and compatibility;
+6. concurrency and reliability;
+7. significant performance problems;
+8. missing tests for demonstrated risks;
+9. violations of explicit repository rules (for example a value object declared
+   as a `struct` instead of a `class`).
+
+Do not report:
+
+* formatting already enforced by an automated formatter;
+* problems already flagged by an `FCExxx` analyzer;
+* naming violations already enforced by repository tooling;
+* speculative problems without a plausible execution path;
+* broad refactoring opportunities unrelated to the pull request;
+* personal style preferences presented as requirements;
+* pre-existing issues not materially affected by the pull request.
+
+When a repeated style problem should be automated by `.editorconfig`, a formatter
+or an analyzer, do not keep adding review comments for each occurrence.
+
+## Writing actionable comments
+
+A comment must be understandable without requiring the author to infer the
+reviewer's intent.
+
+Prefer:
+
+```text
+issue: This property exposes the mutable context dictionary in the public API.
+
+`BuildContext` returns the backing `Dictionary<ErrorContextKey, object?>` directly, so any
+caller can mutate an error's context after the error was created, breaking the immutability
+`ErrorContext` guarantees.
+
+Return `IReadOnlyDictionary<ErrorContextKey, object?>` (as `ErrorContext.Values` does), or
+wrap the dictionary in a `ReadOnlyDictionary` before returning it.
+```
+
+Avoid:
+
+```text
+issue: This method should not be public.
+```
+
+Do not overstate consequences.
+Use conditional language only when the execution path is genuinely conditional:
+
+```text
+issue: When two threads initialize the error catalog concurrently, each can build and cache its own instance.
+
+The lazy initialization checks `_catalog is null` and assigns without synchronization, so
+concurrent callers each run the factory. Whichever assignment lands last wins, while callers
+that already read an earlier instance keep using it.
+
+Guard the initialization with `Lazy<T>` or a lock so the catalog is built exactly once.
+```
+
+Do not use vague formulations such as:
+
+* "maybe";
+* "I'm not a fan";
+* "in my opinion";
+* "this seems weird";
+* "could you take a look?".
+
+When uncertainty is material, use a precise `question:` instead.
+
+## Relationship between an issue and its correction
+
+A confirmed problem and its proposed correction normally belong in the same comment.
+Do not create separate comments such as:
+
+```text
+issue: The documentation is written to several files without rollback.
+```
+
+and:
+
+```text
+suggestion: Write to a temporary directory first.
+```
+
+Prefer one complete comment:
+
+```text
+issue: A failed documentation run can leave a partially written catalog on disk.
+
+GenDoc writes each error page in sequence, overwriting the previous output in place. If a
+write fails midway, the already-written pages remain while the rest stay stale, so the
+published catalog is internally inconsistent.
+
+Write the full set to a temporary directory and swap it in only once every page succeeded,
+or delete the output on failure so the run is all-or-nothing.
+```
+
+A separate `suggestion:` is appropriate only when it describes an independent,
+optional improvement.
+
+## Tests
+
+Do not request a test merely because a changed method has no dedicated test.
+Request a test when it protects a meaningful behavior, boundary or regression.
+
+Use:
+
+```text
+issue (test): No test covers `ErrorCode.Create` rejecting a whitespace code.
+
+This change reworks the validation in `ErrorCode.Create`, but no test exercises the
+whitespace case. `Create` is contractually required to throw `ArgumentException` on null,
+empty or whitespace input; without a test the guard can be removed again without anything
+failing.
+
+Add a test that calls `ErrorCode.Create(" ")` and asserts an `ArgumentException`.
+```
+
+Use `suggestion (test):` when the additional coverage is beneficial but not
+required to make the pull request safe.
+
+## Final review summary
+
+The final review summary must be concise.
+When findings were reported, summarize only:
+
+* the number of blocking findings;
+* the number of non-blocking findings;
+* the principal risk areas.
+
+Do not duplicate every inline comment in the summary.
+When no finding was reported, state clearly that no blocking issue was found.
+The summary itself is not an inline Conventional Comment and therefore does not
+require a label.

From 51ad2352c8bf4ff6364feb2cc4bde172b4ebece8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 13 Jul 2026 08:10:21 +0000
Subject: [PATCH 2/3] docs: link CLAUDE.md to the agent review-feedback rules

AGENTS.md carries the review-feedback escalation rules, but the acting agent
reads CLAUDE.md and not necessarily AGENTS.md. Inline the essentials here and
point to the full section, so the escalation and no-self-merge rules actually
bind the agent that fixes a pull request.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XAzVV5kTFuoTABDYZHSKR1
---
 CLAUDE.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index d171b5d..8bd448e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,3 +74,20 @@ errors should stay structured, documented, and close to the code.
 * Write every pull request title per [`CONTRIBUTING.md`](CONTRIBUTING.md): name the whole change in English; a single-intention PR mirrors its commit header (`type(scope): description`), a multi-intention PR uses a short descriptive title, and issue references stay in the description, not the title.
 * Enable the local commit-message hook once per clone with `git config core.hooksPath .githooks`; the same check runs in CI on every pull request.
 * In PR descriptions, do not invent testing results. Only check items that were actually run.
+
+## Responding to pull request review feedback
+
+When you act on review feedback on a pull request (for example a Codex review),
+follow the escalation rules in [`AGENTS.md`](AGENTS.md) ("Responding to review
+feedback"). The essentials, inlined so they hold even if `AGENTS.md` is not read:
+
+* If you agree and the fix is clear and local, implement it, push, and reply
+  `Resolved in <sha>`.
+* If you believe a finding is wrong, reply with the concrete technical reason and
+  mention `@reefact` to arbitrate — do not argue with the reviewer bot.
+* If a finding needs a human judgement (architecture, a trade-off, an ambiguous
+  requirement, a security or compatibility policy), mention `@reefact` and wait.
+* Never mention both the reviewer bot and `@reefact` on the same thread; cap at
+  two fix/re-review cycles, then escalate to `@reefact`.
+* No agent merges a pull request or enables auto-merge on it — the human
+  maintainer merges.

From 4b3f66339bdc6abe5ed48cd28c997813129bc3a9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 13 Jul 2026 08:30:12 +0000
Subject: [PATCH 3/3] docs: clarify the optional-part notation in the review
 format

A review noted that the `[(decorations)]` / `[discussion]` template could be
read as if the square brackets were literal. State explicitly, in AGENTS.md and
code_review.md, that `< >` is a placeholder and `[ ]` marks an optional part.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XAzVV5kTFuoTABDYZHSKR1
---
 AGENTS.md      | 4 ++++
 code_review.md | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index f6fdab0..55960ca 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,6 +33,10 @@ Every inline comment MUST use exactly this shape, with nothing around it:
 <optional discussion>
 ```
 
+In this shape, `< >` marks a placeholder to replace and `[ ]` marks an optional
+part — write neither the angle brackets nor the square brackets literally.
+Decorations, when present, go in parentheses (for example `(security)`).
+
 - The entire comment is written in **English** — label, decorations, subject and
   discussion. Code identifiers, API names and exception messages are quoted verbatim.
 - Never publish an unlabelled comment.
diff --git a/code_review.md b/code_review.md
index 0fa6607..b34feee 100644
--- a/code_review.md
+++ b/code_review.md
@@ -21,6 +21,10 @@ Every inline review comment must use this format:
 [discussion]
 ```
 
+In this notation, `< >` marks a placeholder to replace and `[ ]` marks an optional
+part — write neither the angle brackets nor the square brackets literally.
+Decorations, when present, go in parentheses (for example `(security)`).
+
 The subject must summarize the finding in one sentence.
 The optional discussion must explain: