feat: add semantic multi-container C3

.github/workflows/ci.yml

@@ -405,6 +405,59 @@ jobs:
           grep -Fq "component" "$workdir/c3/model.c4"
           "${cli[@]}" validate --output "$workdir/c3"
 
+          "${cli[@]}" generate \
+            --model examples/models/multi-c3.c2.v1.json \
+            --output "$workdir/c3-multi" \
+            --c3-container el_beta \
+            --c3-container el_alpha \
+            --c3-container el_alpha \
+            --apply
+          test -s "$workdir/c3-multi/c3.views.c4"
+          grep -Fq "view c3_el_alpha {" "$workdir/c3-multi/c3.views.c4"
+          grep -Fq "view c3_el_beta {" "$workdir/c3-multi/c3.views.c4"
+          test "$(grep -Ec '^[[:space:]]*view c3_' "$workdir/c3-multi/c3.views.c4")" -eq 2
+          grep -Fq "component" "$workdir/c3-multi/model.c4"
+          "${cli[@]}" validate --output "$workdir/c3-multi"
+
+          "${cli[@]}" inspect \
+            --repository examples/fixtures/semantic-c3-dogfood \
+            --integration-report inspection-v1.6.json \
+            --output "$workdir/dogfood.snapshot.json"
+          python3 scripts/build-semantic-c3-dogfood-model.py \
+            "$workdir/dogfood.snapshot.json" \
+            "$workdir/dogfood.c2.json"
+          "${cli[@]}" generate \
+            --model "$workdir/dogfood.c2.json" \
+            --output "$workdir/dogfood" \
+            --c3-container el_ingestion_api \
+            --c3-container el_ingestion_outbox_worker \
+            --c3-container el_consolidation_api \
+            --c3-container el_consolidation_worker \
+            --apply
+          test -s "$workdir/dogfood/semantic-c3-evidence-report.md"
+          test "$(grep -Ec '^[[:space:]]*view c3_' "$workdir/dogfood/c3.views.c4")" -eq 4
+          grep -Fq 'ApplicationService' "$workdir/dogfood/semantic-c3-evidence-report.md"
+          grep -Fq 'PersistenceAdapter' "$workdir/dogfood/semantic-c3-evidence-report.md"
+          grep -Fq 'MessagingConsumer' "$workdir/dogfood/semantic-c3-evidence-report.md"
+          grep -Fq 'MessagingPublisher' "$workdir/dogfood/semantic-c3-evidence-report.md"
+          grep -Fq 'IntegrationAdapter' "$workdir/dogfood/semantic-c3-evidence-report.md"
+          if grep -Fq 'TelemetryNames' "$workdir/dogfood/model.c4"; then
+            echo "Semantic C3 dogfood promoted a utility type."
+            exit 1
+          fi
+          "${cli[@]}" validate --output "$workdir/dogfood"
+
+          dogfood_preview="$("${cli[@]}" generate \
+            --model "$workdir/dogfood.c2.json" \
+            --output "$workdir/dogfood" \
+            --c3-container el_consolidation_worker \
+            --c3-container el_ingestion_api \
+            --c3-container el_consolidation_api \
+            --c3-container el_ingestion_outbox_worker)"
+          [[ "$dogfood_preview" == *"unchanged model.c4"* ]]
+          [[ "$dogfood_preview" == *"unchanged c3.views.c4"* ]]
+          [[ "$dogfood_preview" == *"unchanged semantic-c3-evidence-report.md"* ]]
+
           preview="$("${cli[@]}" generate \
             --model examples/end-to-end/architecture.c2.v1.json \
             --output "$workdir/c2")"

CHANGELOG.md

@@ -4,6 +4,16 @@ Notable changes to Repo2C4 follow [Keep a Changelog](https://keepachangelog.com/
 
 ## [Unreleased]
 
+### Added
+- End-to-end Semantic C3 dogfooding derived from `dotnet-observability-lab`, with persisted bounded structural facts, sanitized external-integration correlation, responsibility-level four-container golden coverage, semantic provenance report, managed regeneration, real CLI/MCP paths and official LikeC4 validation while preserving legacy C3 fallback for older snapshots.
+- Bounded Semantic C3 multi-container support across MCP and Agent: typed `c3Containers` with legacy singular compatibility, deterministic `c3Views` reporting, pre-write ID/budget validation, repeated Agent authorization with evidence-supported subset selection, and exact C3 selection preserved through preview, validation and HITL write approval.
+- Repeatable CLI `--c3-container` selection backed by one canonical multi-container C3 workspace, deterministic per-container LikeC4 views, duplicate-ID normalization, pre-write validation, and managed-output compatibility while preserving the single-container behavior.
+- Bounded Semantic C3 internal/external relation composition with explicit wiring+invocation confidence policy, deterministic edge deduplication, weak-cycle/cross-container safeguards, existing C1/C2 peer reuse, and a signal/missing-signal evidence report.
+- Reviewable Semantic C3 worker/messaging/persistence proposals that merge hosted-service evidence, distinguish supported publish/consume adapters through Integration Evidence, require observed use before promoting repository-shaped persistence, reuse existing C1/C2 external peers, and keep weak/unlinked evidence conservative.
+- Reviewable Semantic C3 HTTP/application proposals that aggregate routes by semantic boundary and distinguish DI-/handler-backed application services from name-only classes.
+- Bounded, cancellation-aware C# structural fact extraction for Semantic C3, covering symbols, DI/wiring, Minimal API/controllers, hosted services, DbContext, messaging role signals and conservative intra-project collaboration facts without build/code execution or source/literal propagation.
+- Additive, versioned Semantic C3 contract foundation with deterministic component taxonomy, stable source-symbol identity, reviewable internal/external relations, conceptual multi-container selection, and a reproducible v1.1.0 dogfooding baseline.
+
 ## [1.1.0] - 2026-10-02
 
 ### Added

README.md

@@ -31,8 +31,9 @@ Repo2C4 keeps AI orchestration outside Core and MCP. Core performs no AI calls,
 
 - **Bounded local inspection:** scans one explicitly authorized local root, skips mandatory sensitive/generated paths and linked path escapes, enforces file/byte/entry budgets, and does not execute repository code.
 - **Traceable .NET evidence:** extracts supported solution/project/source declarations with repository-relative provenance while keeping static declarations and runtime candidates distinct.
+- **Semantic C3:** persists bounded structural C# facts and proposes responsibility-level HTTP/application/worker/messaging/persistence/integration components only when structural evidence supports them; class names alone never become components.
 - **Deterministic LikeC4:** generates reviewable C1/C2 workspaces and validates them with the separately installed official LikeC4 CLI.
-- **Selective C3:** expands exactly one explicitly selected C2 container when enough evidence is available; other containers are not expanded automatically.
+- **Selective multi-container C3:** expands one or more explicitly selected C2 containers when enough evidence is available; repeated selections share one deterministic workspace and unselected containers are not expanded automatically.
 - **Review-first writes:** `generate` previews by default. CLI writes require `--apply`; MCP writes require explicit `dryRun=false`, `write=true`, and an authorized relative destination. Managed-file hashes protect human edits.
 - **CLI:** `repo2c4` exposes onboarding, inspection, optional inference, generation and validation.
 - **MCP stdio server:** `repo2c4-mcp` exposes evidence, generation and validation tools inside one authorized root. Model selection, if any, belongs to the MCP client.
@@ -46,14 +47,14 @@ Repo2C4 currently does **not**:
 
 - prove runtime communication, deployment topology, ownership or container boundaries merely from `ProjectReference`, package presence, SDKs or source candidates;
 - evaluate MSBuild, build or execute the inspected repository, run its hooks/scripts, or read arbitrary source bodies into the public evidence contract;
-- turn every .NET project into a C4 container or generate C3 for every container automatically;
+- turn every .NET project into a C4 container, turn every class into a C3 component, or generate C3 for every container automatically;
 - provide its own diagram renderer/editor—the generated workspace is rendered by LikeC4;
 - support private/authenticated remote Git acquisition, SSH/file URLs, submodules, or analysis that depends on Git LFS;
 - write generated architecture on inspection or inference alone;
 - let the MCP server call a hosted AI provider on its own;
 - remove the need for architectural review. `validate` verifies LikeC4 syntax/workspace integrity, not whether an architectural decision is true.
 
-For the precise security and evidence boundaries, see [contracts](docs/contracts.md), [external integration interoperability](docs/external-integration-boundary.md), [CLI](docs/cli.md), [MCP](docs/mcp.md), and [distribution/security guidance](docs/distribution.md).
+For the precise security and evidence boundaries, see [contracts](docs/contracts.md), [Semantic C3](docs/semantic-c3.md), [external integration interoperability](docs/external-integration-boundary.md), [CLI](docs/cli.md), [MCP](docs/mcp.md), and [distribution/security guidance](docs/distribution.md).
 
 ## Quick Start
 
@@ -85,7 +86,7 @@ repo2c4 inspect \
 
 The resulting snapshot is deterministic for this fixture and can be compared with [`examples/end-to-end/snapshot.v1.json`](examples/end-to-end/snapshot.v1.json).
 
-For external integrations, first run `dotnet repo-inspect /absolute/repository --discover-integrations --output /absolute/repository/artifacts/inspection.json` with DotNetRepoInspector `v1.6.5`, then add `--integration-report /absolute/repository/artifacts/inspection.json` to `repo2c4 inspect`. Repo2C4 imports normalized `external.*` evidence through the public schema `1.6+` JSON boundary; it neither invokes DotNetRepoInspector nor reads its internal assemblies. See the [external integration boundary](docs/external-integration-boundary.md).
+For external integrations, first run `dotnet repo-inspect /absolute/repository --discover-integrations --output /absolute/repository/artifacts/inspection.json` with DotNetRepoInspector `v1.6.5`, then add `--integration-report /absolute/repository/artifacts/inspection.json` to `repo2c4 inspect`. Repo2C4 imports normalized `external.*` evidence through the public schema `1.6+` JSON boundary; it neither invokes DotNetRepoInspector nor reads its internal assemblies. Local inspection also persists bounded metadata-only `semanticC3Facts` for later selective C3 generation. See [Semantic C3](docs/semantic-c3.md) and the [external integration boundary](docs/external-integration-boundary.md).
 
 ### 3. Review the model and preview LikeC4
 
@@ -331,9 +332,9 @@ CLI help is written to stdout. MCP help and diagnostics are written **only to st
 
 
 
-### Selective C3
+### Selective multi-container C3
 
-C1/C2 generation remains the default. To derive a reviewable C3 proposal for exactly one existing C2 container, pass `--c3-container <container-id>` to the CLI or `c3ContainerId` to `generate_likec4` over MCP. The generated component boundaries are evidence-linked, bounded, and kept under review when repository-static signals cannot prove runtime behavior. Other containers are not expanded automatically.
+C1/C2 generation remains the default. The CLI accepts repeated `--c3-container <container-id>`; MCP clients should use the bounded `c3Containers` collection (with legacy `c3ContainerId` preserved for one container); and the Agent accepts repeated `--c3-container` values as an authorization set from which it must choose only evidence-supported targets. Generated component boundaries are evidence-linked, deterministic and reviewable. Unselected or unsupported containers are never expanded automatically.
 
 
 ### Managed regeneration

README.pt-BR.md

@@ -31,8 +31,9 @@ O Repo2C4 mantém a orquestração de IA fora do Core e do MCP. O Core não faz
 
 - **Inspeção local limitada:** examina uma única raiz local explicitamente autorizada, ignora caminhos sensíveis/gerados obrigatórios e escapes por links, aplica budgets de arquivos/bytes/entradas e não executa código do repositório.
 - **Evidências .NET rastreáveis:** extrai declarações suportadas de solution/project/source com proveniência relativa ao repositório, mantendo declarações estáticas e candidatos de runtime semanticamente separados.
+- **Semantic C3:** persiste fatos estruturais C# limitados e propõe componentes por responsabilidade HTTP/application/worker/mensageria/persistence/integração somente quando há suporte estrutural; nome de classe sozinho nunca vira componente.
 - **LikeC4 determinístico:** gera workspaces C1/C2 revisáveis e os valida com a CLI oficial do LikeC4 instalada separadamente.
-- **C3 seletivo:** expande exatamente um container C2 selecionado explicitamente quando há evidência suficiente; os demais containers não recebem C3 automaticamente.
+- **C3 seletivo multi-container:** expande um ou mais containers C2 selecionados explicitamente quando há evidência suficiente; seleções repetidas compartilham um único workspace determinístico e containers não selecionados não recebem C3 automaticamente.
 - **Escrita review-first:** `generate` é preview por padrão. Na CLI, escrita exige `--apply`; no MCP exige `dryRun=false`, `write=true` e um destino relativo autorizado. Hashes dos arquivos gerenciados protegem edições humanas.
 - **CLI:** `repo2c4` oferece onboarding, inspeção, inferência opcional, geração e validação.
 - **Servidor MCP stdio:** `repo2c4-mcp` expõe evidências, geração e validação dentro de uma raiz autorizada. A seleção de modelo, quando existir, pertence ao cliente MCP.

docs/agent.md

@@ -192,20 +192,25 @@ Public terminal statuses are `completed`, `requires_review`, `validation_failed`
 
 A validated LikeC4 workspace does **not** prove that the architecture claims are true. Evidence quality and review status remain visible.
 
-## Selective C3 with the Agent
+## Selective multi-container C3 with the Agent
 
-C1/C2 remain the default. To request C3, first identify the exact ID of a container that already exists in the reviewed C2 proposal, then authorize only that container for the run:
+C1/C2 remain the default. Repeat `--c3-container` to authorize a bounded set of possible C3 targets for the run:
 
 ```bash
 repo2c4-agent \
   --provider ollama \
   --model YOUR_LOCAL_MODEL \
   --repository-root "/absolute/path/to/repository" \
   --c3-container "container_api" \
-  --goal "Document C1/C2 and, only when supported by evidence, propose C3 for container_api."
+  --c3-container "container_worker" \
+  --goal "Document C1/C2 and propose C3 only for relevant containers supported by evidence."
 ```
 
-The ID must be the C2 container's architecture/model ID, not a project name guessed from the repository. The host pins the selected value: repository content and the model cannot switch C3 to another container. If the selected container is absent from the C2 proposal or evidence is insufficient, C3 is omitted rather than invented.
+Up to 8 container IDs may be authorized. These values are an allow-list, not an instruction to expand every listed container. The Agent must explicitly request only the subset relevant to the objective and supported by the reviewed C2 evidence. The host intersects that request with the allow-list, so repository content or model output cannot escalate C3 to another target. Ambiguous or unsupported component boundaries remain `requiresReview` or are omitted.
+
+A single `--c3-container` preserves the prior behavior. For multi-container proposals, the exact selected IDs are carried through dry-run preview, validation, correction attempts and the destination-specific HITL write plan. The approval prompt shows the selected C3 containers before any protected write.
+
+The Agent never receives or authors the internal Semantic C3 structural fact set. It reasons over bounded MCP evidence and a reviewed C2 proposal; MCP privately binds that proposal to canonical inspected facts before generation. Repository text or model output therefore cannot escalate C3 by fabricating structural facts. See [Semantic C3](semantic-c3.md).
 
 ## Human approval and writing
 
@@ -239,6 +244,7 @@ Safe defaults are configurable only inside bounded ranges:
 | Tool calls | `--max-tool-calls` | 40 | 1–100 |
 | Workflow iterations | `--max-workflow-iterations` | 3 | 1–3 |
 | Validation attempts | `--max-validation-attempts` | 2 | 1–3 |
+| Authorized C3 containers | repeated `--c3-container` | 0 | 0–8 |
 | Evidence pages | `--max-evidence-pages` | 20 | 1–50 |
 | Accumulated response | `--max-response-chars` | 32000 | 1024–100000 |
 | Accumulated context | `--max-context-chars` | 64000 | 4096–200000 |

docs/agent.pt-BR.md

@@ -181,20 +181,25 @@ Os status públicos são `completed`, `requires_review`, `validation_failed`, `c
 
 Um workspace LikeC4 válido **não** prova que as afirmações arquiteturais são verdadeiras. Qualidade da evidência e estado de revisão continuam visíveis.
 
-## C3 seletivo com o Agent
+## C3 seletivo multi-container com o Agent
 
-C1/C2 continuam sendo o padrão. Para solicitar C3, primeiro identifique o ID exato de um container já existente na proposta C2 revisada e autorize somente esse container na execução:
+C1/C2 continuam sendo o padrão. Repita `--c3-container` para autorizar um conjunto limitado de possíveis alvos C3 na execução:
 
 ```bash
 repo2c4-agent \
   --provider ollama \
   --model SEU_MODELO_LOCAL \
   --repository-root "/caminho/absoluto/do/repositorio" \
   --c3-container "container_api" \
-  --goal "Documente C1/C2 e, somente com evidência suficiente, proponha C3 para container_api."
+  --c3-container "container_worker" \
+  --goal "Documente C1/C2 e proponha C3 somente para containers relevantes sustentados por evidência."
 ```
 
-O valor deve ser o ID arquitetural/do modelo do container C2, não um nome de projeto inferido do repositório. O host fixa essa seleção: conteúdo do repositório e o modelo não podem trocar o C3 para outro container. Se o container não existir na proposta C2 ou a evidência for insuficiente, o C3 é omitido em vez de inventado.
+Podem ser autorizados no máximo 8 IDs. Esses valores formam uma allow-list; eles não instruem o Agent a expandir todos. O Agent deve solicitar explicitamente apenas o subconjunto relevante ao objetivo e sustentado pelas evidências C2 revisadas. O host intersecta a solicitação com a allow-list, portanto conteúdo do repositório ou saída do modelo não conseguem escalar C3 para outro alvo. Fronteiras ambíguas ou sem suporte permanecem `requiresReview` ou são omitidas.
+
+Uma única ocorrência de `--c3-container` preserva o comportamento anterior. Em propostas multi-container, os IDs efetivamente selecionados são preservados no dry-run, validação, tentativas de correção e plano HITL específico do destino. O prompt de aprovação mostra os containers C3 selecionados antes de qualquer escrita protegida.
+
+O Agent nunca recebe nem cria o conjunto interno de fatos estruturais Semantic C3. Ele raciocina sobre evidências MCP limitadas e uma proposta C2 revisada; o MCP vincula privadamente essa proposta aos fatos canônicos inspecionados antes da geração. Texto do repositório ou saída do modelo não consegue escalar C3 fabricando fatos estruturais. Veja [Semantic C3](semantic-c3.pt-BR.md).
 
 ## Aprovação humana e escrita
 
@@ -228,6 +233,7 @@ Defaults seguros são configuráveis somente dentro de faixas limitadas:
 | Tool calls | `--max-tool-calls` | 40 | 1–100 |
 | Iterações do workflow | `--max-workflow-iterations` | 3 | 1–3 |
 | Tentativas de validação | `--max-validation-attempts` | 2 | 1–3 |
+| Containers C3 autorizados | `--c3-container` repetido | 0 | 0–8 |
 | Páginas de evidência | `--max-evidence-pages` | 20 | 1–50 |
 | Resposta acumulada | `--max-response-chars` | 32000 | 1024–100000 |
 | Contexto acumulado | `--max-context-chars` | 64000 | 4096–200000 |