Add PropertyNamingPolicy support for JSON property naming

[christianhelle]

This PR implements issue #967, adding full user-facing PropertyNamingPolicy support to Refitter.

Changes

• Added PropertyNamingPolicy CLI option (--property-naming-policy with values: PascalCase (default) or PreserveOriginal)
• Updated .refitter file format with propertyNamingPolicy setting in JSON schema
• Implemented PropertyNamingPolicy enum in RefitGeneratorSettings for CLI, Source Generator, and MSBuild
• Full parity across all code generation surfaces: CLI (GenerateCommand), Source Generator (RefitterSourceGenerator), and MSBuild (RefitterTask)
• Updated documentation (README.md, refitter-file-format.md)
• Updated JSON schema (json-schema.json)
• Comprehensive test coverage: CLI, Source Generator, MSBuild, and integration tests
• Validates generated code compiles and works correctly with both naming policies

Related to

• Closes how to keep contract Property Name as original name without Serialization ? #967

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request implements Issue #967, adding a configurable property naming policy feature. It introduces a PropertyNamingPolicy enum (PascalCase, PreserveOriginal), new identifier validation/sanitization via IdentifierUtils, a PreserveOriginalPropertyNameGenerator, and wires the feature through CLI (--property-naming-policy), .refitter configuration, and code generation. Comprehensive tests and documentation are included.

Changes

Cohort / File(s)	Summary
Squad Documentation & Planning .squad/agents/*, .squad/orchestration-log/*, .squad/decisions*, .squad/commit-message.txt, .squad/skills/raw-property-names/SKILL.md	Agent investigation logs, implementation plans, decision records, and test design documentation for Issue #967. Records feasibility assessment, feature design, implementation approval, and comprehensive test coverage planning across four agent phases (Fenster, Hockney, Keaton investigation; Fenster implementation; Hockney test coverage; Keaton review; Scribe finalization).
Core Feature Implementation src/Refitter.Core/Settings/PropertyNamingPolicy.cs, src/Refitter.Core/PreserveOriginalPropertyNameGenerator.cs, src/Refitter.Core/IdentifierUtils.cs, src/Refitter.Core/Settings/RefitGeneratorSettings.cs, src/Refitter.Core/CSharpClientGeneratorFactory.cs	Adds PropertyNamingPolicy enum, PreserveOriginalPropertyNameGenerator class, and IdentifierUtils helper for C# identifier validation and reserved keyword escaping. Updates RefitGeneratorSettings to include new PropertyNamingPolicy property. Modifies CSharpClientGeneratorFactory.Create() to route between generator implementations based on the policy enum.
CLI & Settings Integration src/Refitter/Settings.cs, src/Refitter/GenerateCommand.cs	Adds --property-naming-policy CLI command option to Settings and wires the setting into RefitGeneratorSettings via CreateRefitGeneratorSettings() method.
Test Coverage src/Refitter.Tests/Examples/PropertyNamingPolicyTests.cs, src/Refitter.Tests/GenerateCommandTests.cs, src/Refitter.Tests/SettingsTests.cs, src/Refitter.Tests/SerializerTests.cs	New test class for property naming scenarios (default PascalCase, PreserveOriginal with valid/reserved/invalid identifiers, compilation verification). Extends existing test suites with defaults verification, CLI option binding, and JSON serialization round-trip coverage.
Test Resources src/Refitter.SourceGenerator.Tests/Resources/PropertyNamingPolicy.json, src/Refitter.SourceGenerator.Tests/Refitter.SourceGenerator.Tests.csproj	Adds OpenAPI 3.0.1 specification fixture with properties exercising naming policies. Updates .csproj to embed the resource.
Public Documentation README.md, docs/docfx_project/articles/refitter-file-format.md, docs/json-schema.json	Documents new --property-naming-policy CLI option and .refitter config property (propertyNamingPolicy). Updates JSON schema to add enum-based propertyNamingPolicy field and remove outdated propertyNameGenerator entry. Includes behavior description for keyword escaping and identifier sanitization.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as GenerateCommand
    participant Factory as CSharpClientGeneratorFactory
    participant Policy as PropertyNamingPolicy
    participant Generator as Property Name Generator
    participant Utils as IdentifierUtils
    participant Code as Generated C# Code

    User->>CLI: --property-naming-policy PreserveOriginal
    CLI->>CLI: Parse CLI option into Settings
    CLI->>CLI: CreateRefitGeneratorSettings(settings)
    Note over CLI: Map PropertyNamingPolicy to RefitGeneratorSettings
    
    CLI->>Factory: Create(generatorSettings)
    Factory->>Policy: Check settings.PropertyNamingPolicy
    
    alt PreserveOriginal Policy
        Factory->>Generator: CreatePropertyNameGenerator()
        Note over Factory: Return PreserveOriginalPropertyNameGenerator
    else PascalCase (or other)
        Factory->>Generator: CreatePropertyNameGenerator()
        Note over Factory: Return CustomCSharpPropertyNameGenerator
    end
    
    Generator->>Utils: ToCompilableIdentifier(originalPropertyName)
    Utils->>Utils: Validate identifier characters
    Utils->>Utils: Check reserved keywords
    
    alt Valid identifier
        Utils-->>Generator: Return as-is
    else Reserved keyword
        Utils-->>Generator: Return `@keyword` (verbatim)
    else Invalid identifier
        Utils-->>Generator: Return sanitized with _ prefix/substitutions
    end
    
    Generator-->>Code: Apply [JsonPropertyName] attribute
    Code-->>User: Generated contract with original or transformed property names

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related PRs

• christianhelle/refitter#709: Modifies CreateRefitGeneratorSettings() in GenerateCommand.cs to add new settings mapping (similar code-level integration pattern).
• christianhelle/refitter#928: Updates CLI/settings wiring for generator settings exposure in both GenerateCommand and RefitGeneratorSettings.
• christianhelle/refitter#786: Modifies CreateRefitGeneratorSettings() method to map CLI options into core settings, touching the same settings plumbing infrastructure.

Suggested Labels

enhancement, .NET

Poem

🐰 A naming policy hops through the CLI,
Preserving property names clean and spry,
With keywords escaped and identifiers sane,
The contracts stay true—not PascalCase pain!
@class and _1st, all compile just fine,
Thank IdentifierUtils for the design! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.63% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully addresses issue #967 by implementing PropertyNamingPolicy enum, PreserveOriginal mode, CLI option support, and documentation updates enabling original property name preservation without forced serialization attributes.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #967 objectives. No unrelated modifications detected in code, tests, documentation, or configuration.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add PropertyNamingPolicy support for JSON property naming' accurately summarizes the main change: introduction of PropertyNamingPolicy support for controlling generated property naming.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch preserve-original-property-names

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 90.78947% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.15%. Comparing base (cd4e01f) to head (d114685).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
src/Refitter.Core/IdentifierUtils.cs	90.72%	9 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #969      +/-   ##
==========================================
- Coverage   93.37%   93.15%   -0.22%     
==========================================
  Files          26       27       +1     
  Lines        1645     1797     +152     
==========================================
+ Hits         1536     1674     +138     
- Misses         40       49       +9     
- Partials       69       74       +5     

Flag	Coverage Δ
unittests	93.15% <90.78%> (-0.22%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/docfx_project/articles/refitter-file-format.md (2)

353-356: ⚠️ Potential issue | 🟡 Minor

Trailing comma in JSON schema example.

Line 355 has a trailing comma after the description value which makes the JSON invalid.

Proposed fix

         "contractsOutputFolder": {
             "type": "string",
-            "description": "The output folder for the generated contracts code",
+            "description": "The output folder for the generated contracts code"
         },

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/docfx_project/articles/refitter-file-format.md` around lines 353 - 356,
The JSON schema example contains an invalid trailing comma after the
"description" value in the property object (the block with "type": "string" and
"description": "The output folder for the generated contracts code"); remove the
trailing comma after that "description" line so the object before
"additionalNamespaces" is valid JSON, ensuring the property object correctly
ends without an extra comma.

---

513-514: ⚠️ Potential issue | 🟡 Minor

Invalid JSON syntax in schema example.

Missing comma after the description property on line 513. The JSON block in the documentation will not parse correctly.

Proposed fix

         "codeGeneratorSettings": {
             "type": "object",
-            "description": "Settings for the code generator."
+            "description": "Settings for the code generator.",
             "properties": {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/docfx_project/articles/refitter-file-format.md` around lines 513 - 514,
The JSON schema example has invalid syntax because the "description" property is
missing a trailing comma before the "properties" key; in the doc block where the
snippet shows "description": "Settings for the code generator." and then
"properties": { }, add a comma after the description value so the JSON is valid
(update the example containing the "description" and "properties" keys).

🧹 Nitpick comments (5)

.squad/agents/fenster/history.md (1)

197-287: Implementation plan references unimplemented enum values.

The implementation plan at lines 202 and 210 mentions CamelCase and SnakeCase as potential enum values, but the actual implementation only includes PascalCase and PreserveOriginal. This is internal documentation, but updating it to reflect the final scope would improve accuracy.

Consider updating lines 202 and 210 to reflect the actual implemented enum values (PascalCase, PreserveOriginal) to keep historical documentation consistent with the shipped feature.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.squad/agents/fenster/history.md around lines 197 - 287, Update the
implementation plan text so the enum values listed match the implemented
PropertyNamingPolicy enum: remove or mark as deferred the entries for CamelCase
and SnakeCase and replace "Preserve" with the actual implemented name
"PreserveOriginal" and ensure "PascalCase" is present; search for mentions of
PropertyNamingPolicy, PascalCase, PreserveOriginal, CamelCase, and SnakeCase in
the document and edit the descriptions (the paragraphs referencing the enum and
the "Recommended Implementation Shape" section) to reflect only the shipped
values (PascalCase, PreserveOriginal) or explicitly note the other two as future
work.

.squad/implementation-plan-issue-967.md (1)

25-27: Add language specifier to fenced code block.

The fenced code block is missing a language specifier. Add text or shell for proper syntax highlighting and to satisfy markdownlint rules.

📝 Suggested fix

-```
+```text
 --property-naming-policy [mode]

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @.squad/implementation-plan-issue-967.md around lines 25 - 27, The fenced
code block containing the literal "--property-naming-policy [mode]" is missing a
language specifier; update the triple-backtick fence that wraps
"--property-naming-policy [mode]" to include a language such as text or shell
(e.g., text or shell) so markdownlint and syntax highlighting are
satisfied.

</details>

</blockquote></details>
<details>
<summary>src/Refitter.Core/IdentifierUtils.cs (1)</summary><blockquote>

`228-235`: **Minor: `IsValidIdentifier` returns `false` for valid verbatim keyword identifiers.**

The condition `!IsReservedKeyword(unescapedIdentifier)` causes `IsValidIdentifier("@class")` to return `false`, even though `@class` is a valid C# identifier (the verbatim prefix exists specifically to allow reserved keywords as identifiers).

This doesn't cause functional issues because `ToCompilableIdentifier` handles this correctly by rebuilding and re-escaping, but it means the method's semantics don't fully match its documented purpose of determining "whether the supplied value is already a valid C# identifier."



<details>
<summary>📝 Suggested fix to align semantics with documentation</summary>

```diff
         if (identifier[0] == '@')
         {
             var unescapedIdentifier = identifier.Substring(1);
 
-            return identifier.Length > 1 &&
-                   !IsReservedKeyword(unescapedIdentifier) &&
-                   IsValidIdentifierCore(unescapedIdentifier);
+            return identifier.Length > 1 &&
+                   IsValidIdentifierCore(unescapedIdentifier);
         }
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/Refitter.Core/IdentifierUtils.cs` around lines 228 - 235, The
IsValidIdentifier method incorrectly rejects verbatim identifiers by checking
!IsReservedKeyword on the unescaped identifier; update the logic so that when
identifier starts with '@' you only validate the unescaped text with
IsValidIdentifierCore (and the length check) and do not call IsReservedKeyword,
e.g. make the verbatim branch return identifier.Length > 1 &&
IsValidIdentifierCore(unescapedIdentifier) so `@class` is considered valid; keep
non-verbatim behavior unchanged.
```

</details>

</blockquote></details>
<details>
<summary>src/Refitter.Tests/Examples/PropertyNamingPolicyTests.cs (1)</summary><blockquote>

`11-57`: **Add OpenAPI 2.0 (Swagger) specification tests.**

The tests only use OpenAPI 3.0.1 specification. Per coding guidelines, new code generation features should be tested with both OpenAPI 2.0 and 3.0 specifications to ensure compatibility across spec versions.

Consider adding a parallel set of tests with a Swagger 2.0 spec to verify the `PropertyNamingPolicy` feature works correctly with both specification formats.



As per coding guidelines: "Test new code generation features with both OpenAPI 2.0 and 3.0 specifications".

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/Refitter.Tests/Examples/PropertyNamingPolicyTests.cs` around lines 11 -
57, Add a parallel Swagger 2.0 spec and tests alongside the existing OpenApiSpec
to validate PropertyNamingPolicy across spec versions: create a new constant
(e.g., SwaggerV2Spec) in PropertyNamingPolicyTests mirroring the current
OpenApiSpec but using OpenAPI/Swagger 2.0 format (swagger: "2.0", definitions
instead of components/schemas, paths/responses adapted), then duplicate the
existing test(s) to run against SwaggerV2Spec (call same test helper methods
that consume OpenApiSpec) so the PropertyNamingPolicy behavior is asserted for
both OpenAPI 3.0.1 (OpenApiSpec) and Swagger 2.0 (SwaggerV2Spec).
```

</details>

</blockquote></details>
<details>
<summary>.squad/skills/raw-property-names/SKILL.md (1)</summary><blockquote>

`93-104`: **Test design inconsistency with actual implementation.**

Test 5 suggests that invalid identifiers with hyphens should throw an `InvalidOperationException`, but the actual implementation in `IdentifierUtils.ToCompilableIdentifier` sanitizes them instead (e.g., `pay-method` → `pay_method`). This is confirmed by `PropertyNamingPolicyTests.PreserveOriginal_Minimally_Sanitizes_Invalid_Identifiers` which expects `1st-payment-method` to become `_1st_payment_method`.

The "Implemented Pattern" section (lines 159-172) correctly documents the actual behavior. Consider updating this test design section to align with the sanitization approach rather than rejection.

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In @.squad/skills/raw-property-names/SKILL.md around lines 93 - 104, Update the
test Invalid_Property_Names_With_Hyphens_Are_Rejected to assert the sanitization
behavior instead of expecting an InvalidOperationException: call
GenerateCode(spec) (or the same code path) and verify the resulting property
name matches the sanitized form (e.g., "pay-method" → "pay_method"), aligning
with IdentifierUtils.ToCompilableIdentifier and existing
PropertyNamingPolicyTests.PreserveOriginal_Minimally_Sanitizes_Invalid_Identifiers;
replace the exception assertion with an assertion that the generated model
contains the sanitized identifier.
```

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.squad/decisions/fenster-plan-issue-967.md:

• Around line 15-18: The decision document is out of sync with the implemented
  feature: update the CLI option enum names from Preserve/CamelCase/SnakeCase to
  the shipped names (e.g., PreserveOriginal) and change the scope/phase text from
  “CLI-only Phase 1” to reflect parity across CLI, .refitter, source generator,
  and MSBuild; also update any stale file name references listed in the doc.
  Locate the enum/CLI surface description (lines referencing
  --property-naming-policy and the list of four values), the “Scope (Phase 1)”
  paragraph, and any file name mentions, then replace the old policy names with
  the actual shipped names, change the phase/scope wording to indicate feature
  parity across all surfaces, and correct the referenced file names so the
  decision log matches the implemented behavior.

In @src/Refitter/Settings.cs:

• Around line 33-37: Add XML documentation for the public CLI setting
  PropertyNamingPolicy: add a triple-slash comment above the PropertyNamingPolicy
  property that includes a
  describing that it controls how generated
  contract properties are named, mentions the allowed values (referencing
  PropertyNamingPolicyValues and the Core.PropertyNamingPolicy enum), and
  documents the default value (Core.PropertyNamingPolicy.PascalCase); optionally
  include a or noting it is exposed as the
  "--property-naming-policy" command-line option and any behavior/impact on
  generated contracts.

---

Outside diff comments:
In @docs/docfx_project/articles/refitter-file-format.md:

• Around line 353-356: The JSON schema example contains an invalid trailing
  comma after the "description" value in the property object (the block with
  "type": "string" and "description": "The output folder for the generated
  contracts code"); remove the trailing comma after that "description" line so the
  object before "additionalNamespaces" is valid JSON, ensuring the property object
  correctly ends without an extra comma.
• Around line 513-514: The JSON schema example has invalid syntax because the
  "description" property is missing a trailing comma before the "properties" key;
  in the doc block where the snippet shows "description": "Settings for the code
  generator." and then "properties": { }, add a comma after the description value
  so the JSON is valid (update the example containing the "description" and
  "properties" keys).

---

Nitpick comments:
In @.squad/agents/fenster/history.md:

• Around line 197-287: Update the implementation plan text so the enum values
  listed match the implemented PropertyNamingPolicy enum: remove or mark as
  deferred the entries for CamelCase and SnakeCase and replace "Preserve" with the
  actual implemented name "PreserveOriginal" and ensure "PascalCase" is present;
  search for mentions of PropertyNamingPolicy, PascalCase, PreserveOriginal,
  CamelCase, and SnakeCase in the document and edit the descriptions (the
  paragraphs referencing the enum and the "Recommended Implementation Shape"
  section) to reflect only the shipped values (PascalCase, PreserveOriginal) or
  explicitly note the other two as future work.

In @.squad/implementation-plan-issue-967.md:

• Around line 25-27: The fenced code block containing the literal
  "--property-naming-policy [mode]" is missing a language specifier; update the
  triple-backtick fence that wraps "--property-naming-policy [mode]" to include a
  language such as text or shell (e.g., text or shell) so markdownlint and
  syntax highlighting are satisfied.

In @.squad/skills/raw-property-names/SKILL.md:

• Around line 93-104: Update the test
  Invalid_Property_Names_With_Hyphens_Are_Rejected to assert the sanitization
  behavior instead of expecting an InvalidOperationException: call
  GenerateCode(spec) (or the same code path) and verify the resulting property
  name matches the sanitized form (e.g., "pay-method" → "pay_method"), aligning
  with IdentifierUtils.ToCompilableIdentifier and existing
  PropertyNamingPolicyTests.PreserveOriginal_Minimally_Sanitizes_Invalid_Identifiers;
  replace the exception assertion with an assertion that the generated model
  contains the sanitized identifier.

In @src/Refitter.Core/IdentifierUtils.cs:

• Around line 228-235: The IsValidIdentifier method incorrectly rejects verbatim
  identifiers by checking !IsReservedKeyword on the unescaped identifier; update
  the logic so that when identifier starts with '@' you only validate the
  unescaped text with IsValidIdentifierCore (and the length check) and do not call
  IsReservedKeyword, e.g. make the verbatim branch return identifier.Length > 1 &&
  IsValidIdentifierCore(unescapedIdentifier) so @class is considered valid; keep
  non-verbatim behavior unchanged.

In @src/Refitter.Tests/Examples/PropertyNamingPolicyTests.cs:

• Around line 11-57: Add a parallel Swagger 2.0 spec and tests alongside the
  existing OpenApiSpec to validate PropertyNamingPolicy across spec versions:
  create a new constant (e.g., SwaggerV2Spec) in PropertyNamingPolicyTests
  mirroring the current OpenApiSpec but using OpenAPI/Swagger 2.0 format (swagger:
  "2.0", definitions instead of components/schemas, paths/responses adapted), then
  duplicate the existing test(s) to run against SwaggerV2Spec (call same test
  helper methods that consume OpenApiSpec) so the PropertyNamingPolicy behavior is
  asserted for both OpenAPI 3.0.1 (OpenApiSpec) and Swagger 2.0 (SwaggerV2Spec).

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `b67dd2cc-d626-4bb2-a61c-4d51e55f5382`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 74a94d7b946d11d54dc4bbb3efcfff7b4c79a2af and d11468591f8d63cc38bb47d9981ef3ebaad44620.

</details>

<details>
<summary>📒 Files selected for processing (31)</summary>

* `.squad/agents/fenster/history.md`
* `.squad/agents/hockney/history.md`
* `.squad/agents/keaton/history.md`
* `.squad/commit-message.txt`
* `.squad/decisions.md`
* `.squad/decisions/fenster-plan-issue-967.md`
* `.squad/implementation-plan-issue-967.md`
* `.squad/orchestration-log/2026-03-25T08-07-15Z-fenster.md`
* `.squad/orchestration-log/2026-03-25T08-07-15Z-hockney.md`
* `.squad/orchestration-log/2026-03-25T08-07-15Z-keaton.md`
* `.squad/orchestration-log/2026-03-25T09-16-16Z-fenster.md`
* `.squad/orchestration-log/2026-03-25T09-16-16Z-hockney.md`
* `.squad/orchestration-log/2026-03-25T09-16-16Z-keaton.md`
* `.squad/orchestration-log/2026-03-25T10-34-40Z-scribe.md`
* `.squad/skills/raw-property-names/SKILL.md`
* `README.md`
* `docs/docfx_project/articles/refitter-file-format.md`
* `docs/json-schema.json`
* `src/Refitter.Core/CSharpClientGeneratorFactory.cs`
* `src/Refitter.Core/IdentifierUtils.cs`
* `src/Refitter.Core/PreserveOriginalPropertyNameGenerator.cs`
* `src/Refitter.Core/Settings/PropertyNamingPolicy.cs`
* `src/Refitter.Core/Settings/RefitGeneratorSettings.cs`
* `src/Refitter.SourceGenerator.Tests/Refitter.SourceGenerator.Tests.csproj`
* `src/Refitter.SourceGenerator.Tests/Resources/PropertyNamingPolicy.json`
* `src/Refitter.Tests/Examples/PropertyNamingPolicyTests.cs`
* `src/Refitter.Tests/GenerateCommandTests.cs`
* `src/Refitter.Tests/SerializerTests.cs`
* `src/Refitter.Tests/SettingsTests.cs`
* `src/Refitter/GenerateCommand.cs`
* `src/Refitter/Settings.cs`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Decision log is out of sync with the implemented feature.

This plan still describes Preserve/CamelCase/SnakeCase and “CLI-only Phase 1”, but the PR implements PreserveOriginal and parity across CLI, .refitter, source generator, and MSBuild. The listed file names are also stale in places. Please update this doc so it reflects the shipped behavior.

Suggested doc update

-1. **CLI Surface:** `--property-naming-policy` enum option with 4 values: `PascalCase` (default), `Preserve`, `CamelCase`, `SnakeCase`
+1. **CLI Surface:** `--property-naming-policy` enum option with 2 values: `PascalCase` (default), `PreserveOriginal`

-3. **Scope (Phase 1):** CLI only; defer `.refitter` file support to Phase 2 (source generator/MSBuild)
+3. **Scope:** CLI, `.refitter`, Source Generator, and MSBuild are all supported

-**Out of Scope (Phase 2):**
-- `.refitter` file support
-- Source generator integration
-- MSBuild task integration
-- Schema evolution for polymorphic `IPropertyNameGenerator` deserialization
+**Out of Scope (Future):**
+- Additional naming policies beyond `PascalCase` and `PreserveOriginal`

-- `src/Refitter.Core/PropertyNamingPolicy.cs` — Enum
-- `src/Refitter.Core/PreservingPropertyNameGenerator.cs` — Generator
+ - `src/Refitter.Core/Settings/PropertyNamingPolicy.cs` — Enum
+ - `src/Refitter.Core/PreserveOriginalPropertyNameGenerator.cs` — Generator

Also applies to: 44-48, 55-59

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.squad/decisions/fenster-plan-issue-967.md around lines 15 - 18, The
decision document is out of sync with the implemented feature: update the CLI
option enum names from Preserve/CamelCase/SnakeCase to the shipped names (e.g.,
PreserveOriginal) and change the scope/phase text from “CLI-only Phase 1” to
reflect parity across CLI, .refitter, source generator, and MSBuild; also update
any stale file name references listed in the doc. Locate the enum/CLI surface
description (lines referencing `--property-naming-policy` and the list of four
values), the “Scope (Phase 1)” paragraph, and any file name mentions, then
replace the old policy names with the actual shipped names, change the
phase/scope wording to indicate feature parity across all surfaces, and correct
the referenced file names so the decision log matches the implemented behavior.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add XML documentation for the new public CLI setting.

PropertyNamingPolicy is public API but is missing XML doc comments.

✏️ Suggested patch

+    /// <summary>
+    /// Controls how generated contract properties are named.
+    /// </summary>
     [Description($"Controls how generated contract properties are named. May be one of {PropertyNamingPolicyValues}")]
     [CommandOption("--property-naming-policy")]
     [DefaultValue(Core.PropertyNamingPolicy.PascalCase)]
     public Core.PropertyNamingPolicy PropertyNamingPolicy { get; set; } = Core.PropertyNamingPolicy.PascalCase;

As per coding guidelines, "Include XML documentation for public APIs in C# code".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	[Description($"Controls how generated contract properties are named. May be one of {PropertyNamingPolicyValues}")]
	[CommandOption("--property-naming-policy")]
	[DefaultValue(Core.PropertyNamingPolicy.PascalCase)]
	public Core.PropertyNamingPolicy PropertyNamingPolicy { get; set; } = Core.PropertyNamingPolicy.PascalCase;
	/// <summary>
	/// Controls how generated contract properties are named.
	/// </summary>
	[Description($"Controls how generated contract properties are named. May be one of {PropertyNamingPolicyValues}")]
	[CommandOption("--property-naming-policy")]
	[DefaultValue(Core.PropertyNamingPolicy.PascalCase)]
	public Core.PropertyNamingPolicy PropertyNamingPolicy { get; set; } = Core.PropertyNamingPolicy.PascalCase;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/Refitter/Settings.cs` around lines 33 - 37, Add XML documentation for the
public CLI setting PropertyNamingPolicy: add a triple-slash comment above the
PropertyNamingPolicy property that includes a <summary> describing that it
controls how generated contract properties are named, mentions the allowed
values (referencing PropertyNamingPolicyValues and the Core.PropertyNamingPolicy
enum), and documents the default value (Core.PropertyNamingPolicy.PascalCase);
optionally include a <remarks> or <example> noting it is exposed as the
"--property-naming-policy" command-line option and any behavior/impact on
generated contracts.

[christianhelle]

Related to #973 — the PreserveOriginal property naming policy introduced in this PR surfaced an underlying stack overflow bug in recursive schema traversal, which is being fixed in PR #971.