Handle equivalent duplicate schemas in multi-spec merge

.squad/agents/ash/history.md

@@ -16,6 +16,7 @@
 - `src\Refitter.SourceGenerator\RefitterSourceGenerator.cs` still has a same-directory hint-name collision risk because `CreateUniqueHintName(...)` hashes only the parent directory, not the full `.refitter` path.
 - In the source generator, treat `AdditionalText.GetText(...)` as nullable and convert read/encoding failures into diagnostics; null-forgiving it weakens failure reporting.
 - Review gate for the next safety pass: require targeted tests for source-generator hint-name collisions, OpenAPI-title sanitization including `<`/`>`, and MSBuild runtime-discovery timeout behavior before accepting cleanup claims.
+- 2026-04-28: Approved Parker/Lambert e-conomic multi-spec merge fix after verifying canonical JSON-token equivalence accepts duplicate recursive/shared schemas, conflicting duplicate path/schema/definition/security entries still fail fast, and focused net10.0 TUnit coverage passes.
 
 ## Core Context
 

.squad/agents/dallas/history.md

@@ -8,6 +8,8 @@
 
 ## Learnings
 
+- **2026-04-28T15:21:48.369+02:00 e-conomic multi-spec tooling verdict:** `test\economic.refitter` parses correctly and resolves both relative `openApiPaths`; CLI/MSBuild/source-generator all reach core multi-document merge, where duplicate equivalent schemas (`Error`, then `ProblemDetails`) trigger the fail-fast merge path before validation, so `--skip-validation` cannot help.
+
 - Team initialized on 2026-04-16.
 - **2026-04-28 issue #1045 tooling verdict:** current HEAD CLI accepts `.refitter` files that use only `openApiPaths`; the quoted `'openApiPath' is required` failure string is stale pre-#1057 behavior, while the remaining normalization gap is a core/library consistency concern rather than a current CLI/MSBuild break.
 - **Issue #998 findings (2026-04-16):** MSBuild's first-clean-build path was the real tooling bug; CLI settings loading and the default single-file `Output.cs` behavior were otherwise correct.
@@ -66,3 +68,11 @@
 - Ripley's triage keeps docs/help drift first, then settings/spec-path normalization, then shared `GeneratedFile:` marker cleanup, which matches Dallas's current tooling/doc seams.
 - Lambert's baseline scan stays green for restore/build/test/format, but live-URL tests remain environment-sensitive and should not be used as tooling stability evidence during cleanup.
 
+
+## 2026-04-28: e-conomic Multi-Spec Tooling Validation (PRIMARY FIX IN CORE)
+- `test\economic.refitter` parses correctly, resolves both relative `openApiPaths` under `test\OpenAPI\v3.0\`, each spec generates independently.
+- CLI/MSBuild/source-generator all reach core merge path where duplicate equivalent schemas (`Error`, `ProblemDetails`) trigger fail-fast before validation.
+- Root cause confirmed in `Refitter.Core` not tooling; `--skip-validation` cannot help because merge happens before validation.
+- Proposal: primary fix belongs in core merge semantics (allow duplicate paths/schemas when semantically equivalent); do not split `.refitter` into multiple generation runs.
+- Tooling follow-up (post-core-fix): improve CLI error guidance for merge failures, add `openApiPaths` regression coverage, add relative-path resolution tests, add merge-failure diagnostic tests.
+

.squad/agents/lambert/history.md

@@ -8,6 +8,10 @@
 
 ## Learnings
 
+- **2026-04-28T15:21:48.369+02:00 e-conomic OpenApiPaths regression coverage:** Added intended compile-backed regression coverage for the real `economic-products.json` + `economic-webhooks.json` inputs through `RefitGeneratorSettings.OpenApiPaths`. Current HEAD fails before code generation with duplicate schema `Error`, so the non-empty/buildable assertions become active evidence once the merge fix lands.
+
+- **2026-04-28T15:21:48.369+02:00 e-conomic multi-spec repro:** `test\economic.refitter` fails during generation, not compilation, because `economic-products.json` and `economic-webhooks.json` both define identical `Error` and `ProblemDetails` component schemas; current merge logic throws on the first duplicate schema key (`Error`). Regression coverage should distinguish identical shared schemas from conflicting schema collisions.
+
 - Team initialized on 2026-04-16.
 - **2026-04-28T12:02:17.298+02:00 issue #1045 evidence split:** Current HEAD already covers `.refitter` `openApiPaths` validation/execution and direct `RefitGenerator.CreateAsync(settings)` multi-spec usage. The reliable tester posture is to separate the CLI/settings-file claim from the direct-core-consumer claim, because they need different proofs and the current code/test matrix supports neither regression at HEAD.
 - **2026-04-25 CLI help repro:** src\Refitter\Program.cs intentionally rewrites a no-argument invocation to --help, exits 0, and emits Spectre.Console.Cli help output. Tests in src\Refitter.Tests\GenerateCommandTests.cs should assert semantic help markers like usage, sections, and option names rather than exact formatter-driven spacing.
@@ -71,3 +75,15 @@
 
 - **2026-04-26 final revalidation after cleanup landing:** Current HEAD is green again on the trusted loop: `dotnet restore src\Refitter.slnx`, `dotnet build -c Release src\Refitter.slnx --no-restore`, `dotnet test -c Release src\Refitter.slnx --no-build`, and `dotnet format --verify-no-changes src\Refitter.slnx --no-restore`. The solution test pass now reports 1918 succeeded / 0 failed, and the trusted coverage lane (`dotnet test --project src\Refitter.Tests\Refitter.Tests.csproj -c Release --coverage --coverage-output coverage.cobertura.xml --coverage-output-format xml`) passed 1862 / 1862 with `Refitter.Core.dll` 95.05% line / 96.47% block, `refitter.dll` 97.10% / 99.11%, `Refitter.MSBuild.dll` back to 100% / 100%, and generated `RuntimeProof.dll` unchanged at 80.93% / 71.58%.
 
+## 2026-04-28: e-conomic Multi-Spec Merge Failure Repro (APPROVED FOR FIX)
+- CLI failure repro: `dotnet .\src\Refitter\bin\Release\net9.0\refitter.dll --settings-file test\economic.refitter --no-banner --no-logging --simple-output`
+- Failure: `InvalidOperationException: Cannot merge OpenAPI documents because a duplicate schema 'Error' was found.`
+- Root cause: `economic-products.json` and `economic-webhooks.json` both define identical `Error` and `ProblemDetails` component schemas; current merge throws on first duplicate.
+- Approved test coverage plan:
+  1. `OpenApiDocumentFactoryMergeTests`: add `Merge_With_Equivalent_Duplicate_Schema_Does_Not_Throw` test (OpenAPI 3 docs with identical schema key/body); preserve collision conflict tests
+  2. Optional e-conomic-shaped regression for `Error` schema with descriptions, nullable properties, extensions, `additionalProperties: false`
+  3. Compile-backed regression: two specs with identical error schema and distinct paths; assert generation succeeds and code builds
+  4. Post-fix generated-code validation for `test\economic.refitter`; triage any post-merge generation failures separately
+- Regression gates: existing merge-collision tests must continue passing
+
+- **2026-04-28T15:21:48.369+02:00 e-conomic multi-spec merge final validation:** Release build, focused `OpenApiDocumentFactoryMergeTests` (15 tests), focused `Issue1016_MultiSpecSchemaMergeTests` (7 tests), full Release solution tests, format verification, and the real `test\economic.refitter` CLI generation all passed. The required CLI command generated `test\GeneratedCode\economic.cs` successfully from `economic-products.json` + `economic-webhooks.json` without duplicate schema merge failures.

.squad/agents/parker/history.md

@@ -16,6 +16,7 @@
 - 2026-04-26: Do not refactor ParameterExtractor or interface-emission flow until compile-backed public regressions cover multipart generation and dynamic-query behavior; ParameterExtractorPrivateCoverageTests currently leans on reflection plus RuntimeHelpers.GetUninitializedObject and is too implementation-coupled to be the only safety net.
 - 2026-04-26: The generator pipeline is duplicated between src\Refitter.Core\RefitGenerator.cs Generate()/GenerateMultipleFiles() and among src\Refitter.Core\RefitInterfaceGenerator.cs, RefitMultipleInterfaceGenerator.cs, and RefitMultipleInterfaceByTagGenerator.cs; treat those as Ash-review cleanups because ordering and emitted signature shape are behavior-sensitive.
 - 2026-04-28T12:02:17.298+02:00: Issue #1045 is outdated at current HEAD for Refitter.Core. RefitGenerator.CreateAsync() leaves RefitGeneratorSettings.OpenApiPath null when only OpenApiPaths is supplied, but the core path loader branches on OpenApiPaths first and no downstream Refitter.Core consumer dereferences OpenApiPath afterward; mutating OpenApiPath inside core would be an observable settings-semantics change that conflicts with existing regression expectations.
+- 2026-04-28T15:21:48.369+02:00: e-conomic multi-spec generation fails before code emission in OpenApiDocumentFactory.Merge() on duplicate schema Error; the vendor specs define identical Error schemas, but AreEquivalent() uses System.Text.Json Serializer.Serialize() on NJsonSchema objects, which can hit object cycles and incorrectly treats equivalent shared schemas as conflicts.
 
 ## Core Context
 
@@ -52,3 +53,12 @@
 
 - Ripley's AI-slop sequencing kept Parker's low-risk-first generator guidance intact: docs/help drift first, then settings/marker cleanup, and only later Ash-reviewed generator dedup.
 - Lambert's baseline scan confirmed the repo is currently green on restore/build/test/format, which keeps compile-backed regression work as the gate before any deeper generator cleanup.
+
+## 2026-04-28: e-conomic Multi-Spec Merge Failure Analysis (APPROVED FOR FIX)
+- e-conomic failure is `OpenApiDocumentFactory.Merge()` throwing on duplicate equivalent schemas (`Error`, `ProblemDetails`).
+- Root cause: `AreEquivalent()` uses `System.Text.Json Serializer.Serialize()` on NJsonSchema objects; object cycles cause false-negative on identical schemas.
+- Proposed fix: replace `AreEquivalent()` with OpenAPI-aware canonical comparison using NSwag `ToJson()` or equivalent; keep fail-fast for genuine conflicts.
+- Implementation file: `src\Refitter.Core\OpenApiDocumentFactory.cs` → `MergeIfMissingOrThrowOnConflict()` / `AreEquivalent()`
+- Test coverage: merge equivalence tests, e-conomic-shaped regressions, compile-backed generation validation
+- Constraints: preserve clone-first/non-mutating merge, don't rename schemas, keep relative-path behavior across tooling surfaces
+- 2026-04-28T15:21:48.369+02:00: Implemented duplicate schema equivalence by comparing normalized NSwag/NJsonSchema JSON tokens, with a schema-specific canonical fallback for referenced/cyclic graphs that cannot serialize standalone. This keeps merge semantics fail-fast for real path/schema/definition/security conflicts while allowing equivalent e-conomic `ProblemDetails`/`Error` duplicates.

.squad/agents/ripley/history.md

@@ -10,6 +10,7 @@
 
 - Team initialized on 2026-04-16.
 - 2026-04-28T12:02:17.298+02:00: Issue #1045's new multi-path `.refitter` comment does not reproduce at current HEAD; current CLI validation accepts `openApiPaths`, normalizes relative entries, and the live repro instead surfaced expected merge-collision behavior only when duplicate path specs were used.
+- 2026-04-28T15:21:48.369+02:00: The e-conomic multi-spec failure is a core `OpenApiDocumentFactory` merge-equivalence problem: `economic-products.json` and `economic-webhooks.json` share equivalent `Error` and `ProblemDetails` component schemas, but current NSwag-object serialization comparison false-negatives and throws before validation/generation.
 
 ## Core Context
 
@@ -32,3 +33,10 @@
 - The best remaining behavior-safe seam is still split settings/spec-path normalization across `src\Refitter\SettingsValidator.cs`, `src\Refitter\GenerateCommand.cs`, and `src\Refitter.SourceGenerator\RefitterSourceGenerator.cs`; those paths still disagree on URL detection and only some flows normalize `OpenApiPaths`.
 - The next best tooling seam is the duplicated `GeneratedFile:` marker contract between `src\Refitter\GenerateCommand.cs` and `src\Refitter.MSBuild\RefitterGenerateTask.cs`.
 - After those two, the backlog drops into lower-priority cleanup/refactor territory such as source-generator info-diagnostic shaping, duplicate test pruning, dead output-model cleanup, and deeper core generator dedup.
+
+## 2026-04-28: e-conomic Multi-Spec Merge Failure (APPROVED FOR FIX)
+- Squad triaged the `test\economic.refitter` failure to `OpenApiDocumentFactory.Merge()` throwing on duplicate equivalent schemas.
+- `economic-products.json` and `economic-webhooks.json` share identical `Error` and `ProblemDetails` component schemas; current `AreEquivalent()` calls `Serializer.Serialize()` on NJsonSchema objects and false-negatives on object cycles.
+- Fix approved: replace `AreEquivalent()` with OpenAPI-aware semantic comparison using NSwag canonical JSON representation; keep fail-fast for genuine conflicts.
+- Gates: merge equivalence tests, e-conomic-shaped regressions, compile-backed validation; existing collision tests must pass.
+- Constraints: preserve relative-path behavior, don't edit specs, don't rename schemas in merge.

.squad/decisions.md

@@ -272,3 +272,81 @@
 
 - 2026-04-26: Have all agents use GPT-5.5 for the rest of this session only.
 - 2026-04-26: Commit changes as frequent as possible in small logical groups for a detailed progress history.
+
+## 2026-04-28
+
+### e-conomic Multi-Spec OpenAPI Merge Failure
+
+**Leads:** Ripley (analysis), Parker (core finding), Dallas (tooling validation)  
+**Tester:** Lambert  
+**Status:** TRIAGED AND APPROVED FOR FIX
+
+#### Findings
+
+- `test\economic.refitter` triggers merge failure in `OpenApiDocumentFactory.Merge()` while combining `economic-products.json` and `economic-webhooks.json`.
+- Exception: `InvalidOperationException: Cannot merge OpenAPI documents because a duplicate schema 'Error' was found.`
+- Root cause: `AreEquivalent()` calls `Serializer.Serialize()` on NSwag/NJsonSchema objects; object-cycle behavior returns `false` for semantically identical schemas.
+- Both `Error` and `ProblemDetails` are duplicated and textually equivalent in source JSON; merge fails at `Error` first.
+- Issue is **not** in `.refitter` parsing, path resolution, or individual spec generation—each spec generates successfully in isolation.
+- CLI, source generator, and MSBuild all reach the same merge failure point before code output.
+
+#### Fix Ownership and Scope
+
+**Primary owner:** `Refitter.Core` → `src\Refitter.Core\OpenApiDocumentFactory.cs` → `MergeIfMissingOrThrowOnConflict()` / `AreEquivalent()`
+
+- Replace `AreEquivalent()` with OpenAPI-aware semantic equivalence check (use NSwag `ToJson()` or canonical JSON representation).
+- Keep fail-fast policy for **genuinely conflicting** duplicate path/schema/definition/security entries.
+- Keep clone-first/non-mutating merge behavior.
+- Do **not** edit e-conomic OpenAPI specs; do **not** rename schemas in merge.
+
+#### Approved Test Coverage and Gates
+
+1. Add `OpenApiDocumentFactoryMergeTests`:
+   - `Merge_With_Equivalent_Duplicate_Schema_Does_Not_Throw` — OpenAPI 3 docs with identical schema key and body; both paths preserved.
+   - Preserve existing `Merge_With_Schema_Collision_Throws_And_Does_Not_Mutate_Inputs` for conflicts.
+   - Optional e-conomic-shaped regression for `Error` schema with descriptions, nullable properties, extensions, `additionalProperties: false`.
+
+2. Compile-backed regression: two specs with identical common error schema and distinct paths; assert generation succeeds and generated code builds.
+
+3. Run generated-code validation for `test\economic.refitter` after merge fix; triage any post-merge generation failure separately.
+
+4. Existing merge-collision tests must continue passing.
+
+#### Constraints
+
+- Preserve relative-path behavior across CLI and source generator.
+- Keep `openApiPaths` semantics consistent.
+- OpenAPI 3 `components.schemas` and Swagger 2 `definitions` equivalence must remain aligned.
+- Do not hide genuine schema differences in comparison.
+
+### Ash economic merge review
+
+- Date: 2026-04-28T15:21:48.369+02:00
+
+Verdict: APPROVED
+
+Rationale:
+- `OpenApiDocumentFactory.Merge()` still fails fast on genuinely conflicting duplicate paths, schemas, Swagger 2 definitions, and security schemes while accepting equivalent duplicate schemas.
+- Equivalence is based on normalized OpenAPI/NSwag/NJsonSchema JSON tokens rather than object identity; the recursive schema test covers cyclic schema graphs and the e-conomic regression verifies real multi-spec generation remains buildable.
+- Focused validation passed for `OpenApiDocumentFactoryMergeTests`, `Issue1016_MultiSpecSchemaMergeTests`, and the duplicate-path merge coverage via the net10.0 TUnit executable. A first `dotnet test --filter` attempt failed because this TUnit project does not support that option, not because of product/test failure.
+
+### Lambert e-conomic validation
+
+- Date: 2026-04-28T15:21:48.369+02:00
+- Validation result: PASS
+- Evidence:
+  - `dotnet build -c Release src\Refitter.slnx` passed.
+  - Focused `OpenApiDocumentFactoryMergeTests` passed: 15 succeeded / 0 failed.
+  - Focused `Issue1016_MultiSpecSchemaMergeTests` passed: 7 succeeded / 0 failed.
+  - `dotnet test -c Release src\Refitter.slnx` passed.
+  - `dotnet format --verify-no-changes src\Refitter.slnx` passed.
+  - `dotnet .\src\Refitter\bin\Release\net9.0\refitter.dll --settings-file test\economic.refitter --no-banner --no-logging --simple-output` passed and generated `test\GeneratedCode\economic.cs`.
+- Decision signal: the e-conomic duplicate equivalent schema merge path is validated by focused regression tests, full solution tests, and real CLI generation.
+
+### Parker: e-conomic equivalence implementation
+
+- Date: 2026-04-28T15:21:48.369+02:00
+- Decision: `OpenApiDocumentFactory.AreEquivalent()` should compare normalized OpenAPI/NSwag JSON first and use a narrow NJsonSchema structural fallback only for schemas whose standalone JSON serialization cannot resolve references.
+- Rationale: duplicate schemas from separate vendor specs can be semantically identical while NJsonSchema object graphs contain unresolved/cyclic references; raw serializer comparison falsely reports conflicts.
+- Guardrail: merge still copies missing keys, ignores equivalent duplicates, and throws `InvalidOperationException` for non-equivalent duplicate paths, schemas, definitions, and security schemes.
+- Validation: focused merge tests and Issue1016 multi-spec regression tests passed.

.squad/log/2026-04-28T15-21-48+02-00-economic-openapi-implementation.md

@@ -0,0 +1,12 @@
+# e-conomic OpenAPI implementation session
+
+- Timestamp: 2026-04-28T15:21:48.369+02:00
+- Pre-check: decisions.md size 25628 bytes; decision inbox files 3.
+- Decisions archive gate: No archive entries eligible; decisions.md dated sections begin at 2026-04-21, newer than 30-day cutoff 2026-03-29.
+- Decision inbox: merged 3 new entries and removed 3 inbox files.
+- Implementation: Parker fixed canonical equivalent duplicate schema handling in OpenApiDocumentFactory.
+- Validation: Lambert reported Release build, focused merge tests (15), Issue1016 regressions (7), full solution tests, format verification, and e-conomic CLI generation passed.
+- Review: Ash approved the merge equivalence fix.
+- Cross-agent histories: no append needed; Parker, Lambert, and Ash histories already contained the useful implementation, validation, and review updates.
+- History summarization gate: no history.md files were >= 15360 bytes; none summarized.
+- Health: decisions.md size before 25628 bytes, after 28115 bytes; inbox processed 3; histories summarized 0.

.squad/orchestration-log/2026-04-28T15-21-48+02-00-ash.md

@@ -0,0 +1,8 @@
+# Ash orchestration log — e-conomic OpenAPI implementation
+
+- Timestamp: 2026-04-28T15:21:48.369+02:00
+- Role: Safety Reviewer
+- Model: gpt-5.5
+- Work: Reviewed the canonical merge equivalence implementation and regression evidence.
+- Verdict: APPROVED.
+- Outcome: Fix preserves fail-fast conflict handling while accepting canonical duplicate equivalent schemas.

.squad/orchestration-log/2026-04-28T15-21-48+02-00-lambert.md

@@ -0,0 +1,8 @@
+# Lambert orchestration log — e-conomic OpenAPI implementation
+
+- Timestamp: 2026-04-28T15:21:48.369+02:00
+- Role: Tester
+- Model: gpt-5.5
+- Work: Added e-conomic regression coverage in src\Refitter.Tests\RegressionTests\Issue1016_MultiSpecSchemaMergeTests.cs.
+- Validation: Release build, focused merge tests, focused Issue1016 tests, full Release solution tests, format verification, and e-conomic CLI generation all passed.
+- Outcome: Generated 	est\GeneratedCode\economic.cs from the real e-conomic settings file.