# DSDX v1 (`ds2 v1;`) 전 모듈 이슈 제보 규격, 100+ 대규모 서브에이전트 군집 대응 및 2-Track(Experimental/Stable) MCP 운영 가이드

- **문서 ID**: `DSDX-ISSUE-OPS-1`
- **적용 대상**: 외부 클라이언트(개발자 · AI 에이전트 · 현업 사용자), 코어/런타임 메인테이너, 자율 서브에이전트 군집(`dsdx-issue-triage`, `dsdx-issue-reproducer`, `dsdx-module-solver`, `dsdx-release-gatekeeper`)
- **공개 엔드포인트 및 공식 이슈 트래커**:
  - **1순위 개발자 이슈(`Tier-DEV`) 공식 등록처 (GitLab Work Items)**: **`http://dualsoft.co.kr:8081/dualsoft/dxax/-/work_items`**
  - **정식(Stable) MCP 채널**: `https://dualsoft.ai/mcp` (`channel = "stable"`)
  - **실험(Experimental/Canary) MCP 채널**: `https://dualsoft.ai/mcp-exp` (`channel = "experimental"`)
  - **이슈 제보 가이드 원문**: `https://dualsoft.ai/issue-guide`
- **연관 정본 문서**: [00_DS2_헌장과_아키텍처.md](00_DS2_헌장과_아키텍처.md), [01_DS2_언어명세.md](01_DS2_언어명세.md), [05_SPEC-05_인수검증_매트릭스_출시기준.md](05_SPEC-05_인수검증_매트릭스_출시기준.md)

---

## 1. 제보 주체 3대 채널 분류 및 최우선 순위(`Tier-DEV` 1순위) 정책

외부에서 유입되는 모든 이슈는 제보 루트와 기술적 파급력에 따라 **3대 티어(`Tier-DEV`, `Tier-AGENT`, `Tier-USER`)**로 자동 분류되며, **`http://dualsoft.co.kr:8081/dualsoft/dxax/-/work_items`로 접수되는 개발자 이슈(`Tier-DEV`)에 절대적 1순위**를 부여합니다.

| 우선순위 등급 | 티어 코드 | 제보 주체 및 공식 접수 루트 | 대상 결함 유형 | 목표 대응 SLA 및 반영 트랙 |
| :--- | :--- | :--- | :--- | :--- |
| **1순위 (최우선)** | **`Tier-DEV`**<br>(`P0-Blocker` / `P1-Critical`) | **개발자 채널 (공식 Work Items)**<br>**`http://dualsoft.co.kr:8081/dualsoft/dxax/-/work_items`**<br>(코어·컴파일러·PLC·런타임·통합 엔지니어) | • 4대 완전성 기준 위반(선언 순서 의존, 역방향 화살표 허용, `SCAN-1` vs `VerifyST` 파형 괴리)<br>• F# 코어 스파인(`M1..M5`, `M7`) 타입/패턴매칭/IR 직렬화 오류<br>• 5-Zone ST / PLCopen XML / LS XG5000(`LS_XG5000_XGI_COMPACT/1`) 코드젠 결함<br>• `DSDX-MCP/1.0` 및 `urn:dsdx:sdf:1.0` 스키마 계약 위반 | **즉시 최우선 착수 (Batch 0)**<br>재현 테스트(`Red`) 작성 → `mcp-exp` 즉시 패치 → 5단계 게이트 검증 후 `mcp`(Stable) 최우선 승격 |
| **2순위** | **`Tier-AGENT`**<br>(`P1-High` / `P2-Normal`) | **AI 에이전트 채널**<br>(`https://dualsoft.ai/mcp-exp` · `https://dualsoft.ai/mcp` JSON-RPC 리포트 및 Work Items 연동) | • 28개 `dsdx.*` MCP 도구 호출 시 결정론적 예외/타임아웃<br>• `MINTING-4ID-1` 4종 ID 발급 누락 또는 `AAS-REPO-REG-1` 스테이징 트랜잭션 불일치<br>• 브라운필드 DSD 사전선별(`M6`) 가중치/클리네 3치 정리 오차 | **구조화 자동 재현 착수 (Batch 1)**<br>JSON-RPC 페이로드 해시(`inputSha256`) 기반 자동 클러스터링 후 `mcp-exp` 반영 |
| **3순위** | **`Tier-USER`**<br>(`P2-Normal` / `P3-Minor`) | **현업 사용자 채널**<br>(공정·시운전 엔지니어, 웹 스튜디오 `https://dualsoft.ai/` UI 피드백) | • 웹 스튜디오(`DS2-3D-SYNC-1` 뷰어, 파형 테이블) 표시 개선<br>• 도메인 예제(`.ds2`) 추가 요청, 진단 메시지 가독성 및 문서 보완 | **정기 배치 반영 (Batch 2)**<br>코어 의미론에 영향이 없는 범위에서 UI/문서 개선 후 릴리스 합류 |

### 1.1 개발자 이슈(`Tier-DEV`) 상세 등록 절차 (`http://dualsoft.co.kr:8081/dualsoft/dxax/-/work_items`)

개발자 이슈는 최우선(1순위) 자동 분류 및 담당 모듈 서브에이전트(`dsdx-module-solver`)의 즉각 투입을 위해 아래 절차에 따라 등록합니다.

1. **Work Items 페이지 접속**:
   - 브라우저에서 **`http://dualsoft.co.kr:8081/dualsoft/dxax/-/work_items`**에 접속한 뒤 우측 상단의 **`New item`** (또는 **`New issue`**) 버튼을 클릭합니다.
   - 템플릿 선택창(`Choose a template`)에서 **`01_Tier_DEV_Developer_Issue`**([01_Tier_DEV_Developer_Issue.md](../.gitlab/issue_templates/01_Tier_DEV_Developer_Issue.md))를 선택합니다.
2. **표준 제목 규칙(Title Convention) 작성**:
   - 형식: **`[Tier-DEV][P0|P1][M1..M7] 핵심 증상 한 줄 요약`**
   - 예시 1 (런타임 `M4` 결함): `[Tier-DEV][P0][M4] 자기 사이클 W |> W 후속 스캔 ElapsedMs 초기화 오류`
   - 예시 2 (코드젠 `M3` 결함): `[Tier-DEV][P1][M3] LS_XG5000_XGI_COMPACT/1 심볼 CSV 30자 초과 ASCII 절단 누락`
   - 예시 3 (파서 `M1` 결함): `[Tier-DEV][P0][M1] 다차원 배열 Work[1..4] 전개 시 MINTING-4ID-1 SceneNodeId 중복`
3. **모듈 코드(`M1`~`M7`) 및 다단계 의존 순서(`[Step-01]`~`[Step-NN]`) 체크**:
   - 본문 상단의 체크박스에서 대상 모듈(`M1`~`M7`)을 정확히 지정하면, 100개 이상의 이슈가 동시에 몰리더라도 `dsdx-issue-triage`가 파일 충돌 없이 모듈별 전담 서브에이전트에 즉시 샤딩(Sharding)합니다.
   - 여러 이슈가 연쇄적인 AST/IR → Runtime/Codegen → Host/UI 의존성을 가질 경우 제목에 **`[Step-01]` ~ `[Step-10]`** 순번을 명시해 주시면 선행 기반부터 순서대로 충돌 없이 구현합니다.
4. **무결점 즉시 구현을 위한 5대 필수 스냅샷(`SNAPSHOT-FIRST-1`) 첨부 (필수!)**:
   - 서브에이전트가 추측 없이 1회 패스로 100% 정확하게 구현·검증할 수 있도록 아래 **1.2절의 5대 필수 스냅샷**을 반드시 포함해 주십시오.

### 1.2 무결점 즉시 구현을 위한 5대 필수 스냅샷 규격 (`SNAPSHOT-FIRST-1` — 스냅샷 필수 지침)

현재 접수되는 이슈 스타일(선행 `dualsoft/dx` 이력 `#18`~`#31`: UX 개편 시안, Step-01~10 스펙 확장, AI 에이전트 JSON-RPC 재현)을 분석한 결과, **아래 5대 스냅샷이 포함된 이슈는 모호성 0%로 즉시 완벽하게 구현·검증**됩니다. 이슈 등록 시 해당 유형의 스냅샷을 **필수로 첨부**해 주십시오.

| 스냅샷 구분 | 필수 적용 대상 | 반드시 포함해야 할 스냅샷 및 상세 명세 항목 |
| :--- | :--- | :--- |
| **① 시각 화면 스냅샷 (Visual UI/UX & 3D Snapshot)** | `/play` · `/play-exp` 웹 스튜디오, 3D 디지털 트윈, 파형 테이블, HMI 작화, SVG 도면 이슈 (`#18`~`#20` 스타일) | • **화면 캡처 또는 목표 UX 목업 이미지 필수 첨부 (`![스냅샷](http://dualsoft.co.kr:8081/dualsoft/dxax/uploads/...)`)**<br>• **대상 DOM ID 및 CSS 토큰 명시**: 예: `#twin-svg`, `#waveform-box`, `#adv-dock`, `#pill-verify`, 배경 `#090D16`, 비율 `28% / 44% / 28%`<br>• **인터랙션 트리거 및 상태 전이 명시**: 클릭/단축키(`Ctrl+Enter`) 입력 시 변경되어야 할 정확한 텍스트·배지·하이라이트 동작 |
| **② 독립 실행형 원문 스냅샷 (Self-Contained `.ds2` Snapshot)** | 모든 컴파일러(`M1`), IR(`M2`), 코드젠(`M3`), 런타임(`M4`) 이슈 (`#21`~`#28`, `#31` 스타일) | • **공유 상태(`activeSource`)에 의존하지 않는 완결된 `ds2 v1;` 전문 첨부**<br>• `dsdx.verify.run`이나 `dsdx.scene.render` 호출 시 이전 클라이언트의 활성 프로젝트와 섞이지 않도록 반드시 요청 `arguments` 안에 `"source": "ds2 v1; ..."` 전문을 직접 포함하여 캡처할 것 |
| **③ JSON-RPC 요청/응답 Before & After 스냅샷 (`dsdx-issue/1.0`)** | MCP 도구(`28 Tools`), 호스트(`M7`), 에이전트 연동 이슈 (`#30`, `#31` 스타일) | • **Request 스냅샷**: 실제 전송한 JSON-RPC 2.0 `method`, `params.name`, `params.arguments` (직속 또는 `arguments.payload` 중첩 여부 명시) 및 `inputSha256`<br>• **Actual 스냅샷**: 현재 서버가 반환한 원본 JSON 응답 발췌 또는 전체 첨부(`.json` / `.zip`) + 관찰 당시 저장소 `commit` 해시<br>• **Expected 스냅샷**: 기대하는 **정확한 JSON 키 이름(`camelCase`)**, 배열/객체 구조, 특정 스캔(`Scan #k`)에서의 정확한 상태값 |
| **④ 스캔 타임라인 & 수식/시그니처 스냅샷 (Scan & Formula Contract)** | 런타임 점화식(`SCAN-1`), `VerifyST`, 안전 폴트(`HS01..05`), 엔지니어링 서비스(`SVC-10..21`), DSD(`B-Gate 1~4`) (`#21`~`#29` 스타일) | • **스캔 번호별 기대 파형 표**: 예: `Scan #0: Feed=Going, Clamp=Ready` → `Scan #3: Feed=Finish, Clamp=Going`<br>• **정확한 F# 모듈/함수 시그니처 및 레코드 필드명**: 예: `CodegenEngine.generateIoBomPackage`, `IrWork.ResolvedWatchdogMs`<br>• **정규 수식 및 경계 조건**: 예: $T_{\text{wd}}(W) = \max(\lfloor 2.0 \times \text{duration}(W)\rfloor + \text{sensing}(W) + 300, 1000)$ |
| **⑤ 자동 채점 단언문 스냅샷 (Executable Acceptance Assertion)** | 모든 `Tier-DEV` 버그 수정 · 기능 개선 · 스펙 제안 | • 이슈 하단 **`완료 검증 기준(Acceptance Criteria)`**에 Python 또는 F# 단언문 형태로 합격 기준을 1~3줄 명시:<br>  예: `assert res["irTrace"][3]["phases"]["볼팅완성"] == "Going"`<br>  예: `assert promo["promoted"] is False and promo["targetVersion"] == "Ver01"` |

> [!IMPORTANT]
> **구현 난이도와 모호성을 낮추는 핵심 작성 팁 3가지**
> 1. **외부 로컬 HTML/스크립트와 MCP 서버 책임 분리**: 브라우저 로컬 타이머로 만든 데모 화면의 차이는 서버 버그 증거로 쓰지 말고, 반드시 **`https://dualsoft.ai/mcp` (또는 `/mcp-exp`)의 JSON-RPC 요청·응답 스냅샷**을 기준으로 기대값과 실제값을 대조해 주십시오.
> 2. **필드명(Key Name)과 단위 고정**: 새 스펙 제안 시 반환 JSON 필드명을 한글 설명으로만 적지 말고 정확한 영문 키(예: `timingParameters`, `rpnSummary`, `remainingUsefulCycles`, `attachedSubTokens`)와 단위(`ms`, `%`, `cycles`)를 지정해 주시면 호스트 직렬화 코드까지 한 번에 정확히 연결됩니다.
> 3. **대용량 재현 자료는 `.zip` 또는 마크다운 이미지로 직접 첨부**: GitLab Work Items 편집창에 스크린샷 이미지(`.png`/`.jpg`)나 요청/응답 원본 묶음(`.zip`)을 드래그 앤 드롭으로 첨부하면 서브에이전트가 즉시 다운로드하여 재현 테스트에 반영합니다.

---

## 2. 7대 모듈(`M1`~`M7`) 경계 및 모듈별 무결성 이슈 제보 규격

이슈를 올릴 때 아래 **7대 모듈 코드(`M1`~`M7`)** 중 하나를 명시하면, 담당 모듈 서브에이전트(`dsdx-module-solver`)가 파일 충돌 없이 즉시 정확한 소스 위치에서 원인을 격리하고 수정합니다.

| 모듈 ID | 어셈블리 / 패키지 | 정본 소스 파일 경로 | 담당 도메인 및 불변식 | 이슈 제보 시 필수 포함 정보 (Minimal Reproducible Artifact) |
| :--- | :--- | :--- | :--- | :--- |
| **`M1`** | `Dsdx.Core` | [Core.fs](../src/Dsdx.Core/Core.fs)<br>[ds2-v1.ebnf](../grammar/ds2-v1.ebnf) | • `ds2 v1;` 파서 및 정규 포맷터<br>• 단방향 봉인형 확장 `SDF`(`DSDX-SDF-ENRICHED-1`) 및 무손실 마이그레이션(`DSDX-MIGRATE-1`)<br>• `MINTING-4ID-1` 4종 ID 결정론적 발급<br>• 정적 진단(`DS2-E001..E024`, `DS2-W001..W007`) | 1. 최소 재현 `.ds2` 소스 코드(`ds2 v1; ...`)<br>2. 기대 진단 코드(예: `DS2-E001`) 또는 기대 정규 포맷 출력<br>3. 실제 발생한 파서 예외 또는 왕복 불일치 diff |
| **`M2`** | `Dsdx.Ir` | [Ir.fs](../src/Dsdx.Ir/Ir.fs) | • `SDF → ControlProject IR`(`dsdx-ir/1.0`) 낮춤(Lowering)<br>• 7대 정준 버킷(`B0..B6`) 정렬 및 선언/문장 순서 불변성<br>• 시스템 스코프 결박 `EntryWorkIds` 및 자기 사이클(`SelfCycleRearm`) 추출 | 1. 입력 `.ds2` 또는 SDF JSON<br>2. 문제되는 Work/EdgeGroup 식별자(`uid`, `qualifiedId`, `edgeId`)<br>3. 기대 IR 속성값(`isReset`, `isTransfer`, `selfCycleRearm`) vs 실제 IR 출력 |
| **`M3`** | `Dsdx.Codegen` | [Codegen.fs](../src/Dsdx.Codegen/Codegen.fs)<br>[ls-xg5000-profile.json](../contracts/ls-xg5000-profile.json) | • 5-Zone IEC 61131-3 ST 코드젠(Zone 1~Zone 5 고정 순서)<br>• PLCopen XML, LS XG5000(`LS_XG5000_XGI_COMPACT/1`), Siemens S7-1500 번들 및 12대 투영(`SVC-10..21`) | 1. 타깃 프로파일(`LS_XG5000_XGI_COMPACT/1` 등)<br>2. 문제 발생 Zone 번호(Zone 1: Input/Timer, Zone 2: Reset-Win, Zone 3: Start, Zone 4: Next-State, Zone 5: Output/Token)<br>3. 생성된 ST/XML/CSV 라인과 기대 제어 수식 |
| **`M4`** | `Dsdx.Runtime` · `Dsdx.Rt` | [Runtime.fs](../src/Dsdx.Runtime/Runtime.fs)<br>[Rt.fs](../src/Dsdx.Rt/Rt.fs)<br>[scan-golden.json](../examples/scan-golden.json) | • `SCAN-1` 이산 점화식 실행 엔진($\Delta t = 10\text{ms}$) 및 `Dsdx.Rt` 0-Allocation 스캔 커널(`DSDX-RT-ZEROALLOC-1`)<br>• 무-AST 독립 검증기(`VerifyStEngine`) 및 8종 변이 하네스(`M1..M8`)<br>• `DS2-3D-SYNC-1` 기구학 자세($\mathbf{q}_n(d)$, `q_committed` 래치) 및 `MergedSubRoots` 추적 | 1. 초기 토큰 배치(`initTokens`) 및 센서 오버라이드(`sensorOverrides`)<br>2. 괴리가 발생한 스캔 번호(`scan #n`, `time_ms`)<br>3. 해당 스캔의 `irTrace` vs `stTrace` / `RtScanKernel` (`phases`, `outputs`, `tokens`, `q_committed`) |
| **`M5`** | `Dsdx.Aas` | [Aas.fs](../src/Dsdx.Aas/Aas.fs)<br>[sdf.schema.json](../contracts/sdf.schema.json) | • Tri-Plane AAS 저장소(`Repository` · `HotPlane` · `Type3Sandbox`)<br>• `/staging/{txId}/submodels` 2단계 원자적 승격(`SM-01..SM-07`)<br>• `Ver01(Shadow) → Ver02(SILS) → Ver03(Active)` 승격 게이트 | 1. 대상 `shellId`(Base64URL 무패딩) 및 서브모델(`SM-01`~`SM-07`)<br>2. 스테이징 트랜잭션 ID(`txId`) 및 `VerifyReport` 증거 상태<br>3. 기대 승격 상태(`COMMITTED` / `Ver03`) vs 실제 반환값 |
| **`M6`** | `Dsdx.Dsd` | [dsdx_dsd_preselect.py](../src/Dsdx.Dsd/dsdx_dsd_preselect.py)<br>[dsdx_dsd_decoder.py](../src/Dsdx.Dsd/dsdx_dsd_decoder.py)<br>[03_SPEC-03_도구_API_에이전트_IDE_웹_운영계약.md](03_SPEC-03_도구_API_에이전트_IDE_웹_운영계약.md) | • 공식 **`DSD` (`DS Decoder`, `Digital Segment Decoder`)**: 오메가($\Omega=1, \Phi=1$) 6대 수학 법칙(`DSDX-DSD-OMEGA-1`)<br>• Phase-0 3단계 태그 사전선별(`-84.22%` / `-94.79%` / `-98.52%`) 및 5-Tier 동적 가중치(`0.52 > 0.48`)<br>• 소프트 오메가 엔트로피 $\widetilde{\Omega}_i(m)$ · 무알람 품질 NG 지수(`QualityNgImpactIndex`) · 잔여 수명(`RUC`) | 1. 대상 PLC 벤더/벤치마크 라인(`LS-XGI`, `Fuji MICREX-SX`, `Mitsubishi GX Works2`)<br>2. 입력 태그/래더 조건 및 로그 유무(`full` vs `prelog`)<br>3. 기대 Tier-A 선별 수 / $\Omega_i^{(k_i)}$ / RUC vs 실제 계산 결과 |
| **`M7`** | `Dsdx.Host` | [Program.fs](../src/Dsdx.Host/Program.fs)<br>[studio.html](../src/Dsdx.Host/studio.html)<br>[host.schema.json](../contracts/host.schema.json) | • ASP.NET Core / Kestrel HTTP & Stdio MCP 서버<br>• 28개 정규 `dsdx.*` 오퍼레이션 레지스트리 및 영속 워크스페이스 원장<br>• SHA-256 감사 해시 체인 및 Dual-Track(`/mcp` vs `/mcp-exp`) 라우팅 | 1. 호출 채널(`https://dualsoft.ai/mcp` 또는 `https://dualsoft.ai/mcp-exp`)<br>2. 요청 JSON-RPC 2.0 또는 `/api/host` 봉투(`operation`, `request_id`, `payload`)<br>3. 기대 HTTP 상태/JSON 응답 vs 실제 응답 |

---

## 3. 정규 이슈 제보 템플릿 (Canonical Issue Payload)

개발자(`Tier-DEV`), AI 에이전트(`Tier-AGENT`), 현업 사용자(`Tier-USER`) 모두 아래 **마크다운 템플릿** 또는 **JSON 페이로드(`dsdx-issue/1.0`)** 형식으로 제보할 수 있습니다.

### 3.1 개발자 · 사용자용 마크다운 이슈 템플릿

````markdown
### [DSDX-ISSUE] 요약 제목 (예: [Tier-DEV][M4] 자기 사이클 W |> W 후속 스캔 ElapsedMs 초기화 오류)

- **제보 채널 티어**: `Tier-DEV` (1순위) | `Tier-AGENT` (2순위) | `Tier-USER` (3순위)
- **대상 모듈**: `M1 (Dsdx.Core)` | `M2 (Dsdx.Ir)` | `M3 (Dsdx.Codegen)` | `M4 (Dsdx.Runtime)` | `M5 (Dsdx.Aas)` | `M6 (Dsdx.Dsd)` | `M7 (Dsdx.Host)`
- **발생 트랙 및 버전**: `experimental (https://dualsoft.ai/mcp-exp)` | `stable (https://dualsoft.ai/mcp)`
- **위반된 완전성 기준**: `기준 1 (의미 일관성)` | `기준 2 (최소 표현 완결성)` | `기준 3 (의미 보존과 검증 가능성)` | `기준 4 (AI-Native Sim2Real 완결성)` | `해당 없음`

#### 1. 최소 재현 입력 (`.ds2` 코드 또는 MCP JSON-RPC 요청)
```ds2
ds2 v1;
project Repro {
    system S {
        flow F {
            work A finished { duration 20ms; }
            A |> A;
        }
    }
}
```

#### 2. 재현 절차 및 호출 오퍼레이션
- 호출 도구: `dsdx.verify.run` (`{"scans": 5}`)

#### 3. 기대 결과 (Expected Behavior)
- Scan #0에서 `A`가 `Finish`된 직후 `SelfCycleRearm`에 의해 Scan #1에서 `Going`으로 재장전되어야 함.

#### 4. 실제 결과 (Actual Behavior)
- 실제 반환된 파형 또는 오류 메시지 기재
````

### 3.2 AI 에이전트 · 자동화 클라이언트용 JSON 이슈 제보 규격

외부 AI 에이전트는 아래 정규 JSON 구조체를 재현 자료로 작성하고, 사용자가 허용한 이슈 트래커에 첨부합니다. `dsdx.audit.append` 및 `dsdx.issue.report`는 현재 Host/MCP에 구현된 접수 도구가 아닙니다. `dsdx.audit.query`는 기존 감사 기록을 읽는 도구이며 이슈를 등록하지 않습니다. 실제 트래커가 반환한 이슈 ID와 URL이 없으면 접수 완료로 표시하지 않습니다. 공개 안내는 `https://dualsoft.ai/issue-guide`에서 확인할 수 있으며 GitLab 접속에는 별도 로그인·네트워크 접근 권한이 필요할 수 있습니다.

이 문서의 군집 대응·완성도 점수·담당 배정은 운영 절차입니다. 현재 실행 주체는 단일 MAIN과 필요 시 위임한 서브에이전트이며, 자동 접수 API가 점수나 담당자를 반환한다고 가정하지 않습니다.

```json
{
  "issueSchema": "dsdx-issue/1.0",
  "reporterTier": "Tier-DEV",
  "priority": "P0",
  "module": "M4",
  "channel": "experimental",
  "completenessCriterion": 3,
  "operation": "dsdx.verify.run",
  "reproduction": {
    "ds2Source": "ds2 v1;\nproject P {\n    system S {\n        flow F {\n            work A finished {\n                duration 10ms;\n            }\n        }\n    }\n}\n",
    "payload": { "scans": 10 },
    "expected": { "evidenceStatus": "VERIFIED_PASS", "firstDivergence": null },
    "actual": { "evidenceStatus": "VERIFIED_FAIL", "firstDivergence": 2 }
  }
}
```

---

## 4. 100+ 대규모 동시 이슈 폭주 시 서브에이전트 군집(Swarm) 대응 프로토콜

한 번에 100개 이상의 이슈가 동시에 접수될 경우, 단일 에이전트가 순차 처리하면 컨텍스트 포화와 파일 수정 충돌이 발생합니다. 이를 방지하기 위해 **4단계 파이프라인 및 7모듈 샤딩 서브에이전트 군집(`SWARM-RESPONSE-100`)**으로 대응합니다.

```mermaid
flowchart TD
    A["외부 이슈 대량 유입 (1~100+건)<br/>Tier-DEV / Tier-AGENT / Tier-USER"] --> B["Stage 1: dsdx-issue-triage<br/>• Tier-DEV(1순위) 최우선 정렬<br/>• 동일 근본 원인(RCC) 중복 제거<br/>• 7대 모듈(M1~M7) 샤딩 배정"]
    B --> C["Stage 2: dsdx-issue-reproducer (병렬)<br/>• 각 RCC 클러스터를 최소 .ds2 / JSON-RPC 실패 테스트(Red)로 변환"]
    C --> D1["M1 Solver<br/>(Core.fs)"]
    C --> D2["M2 Solver<br/>(Ir.fs)"]
    C --> D3["M3 Solver<br/>(Codegen.fs)"]
    C --> D4["M4 Solver<br/>(Runtime.fs)"]
    C --> D5["M5/M6/M7 Solvers<br/>(Aas/Dsd/Host)"]
    D1 & D2 & D3 & D4 & D5 --> E["Stage 4: dsdx-release-gatekeeper<br/>1) dotnet build (0 Warn, 0 Err)<br/>2) Dsdx.Host --self-test (8/8 Mutants)<br/>3) spec_probe.py & platform_e2e_test.py"]
    E --> F["Experimental MCP 선반영<br/>https://dualsoft.ai/mcp-exp"]
    F --> G["카나리 검증 통과 후 Stable 무중단 승격<br/>https://dualsoft.ai/mcp"]
```

### 4.1 4대 전용 서브에이전트 역할 및 운영 수칙

1. **`dsdx-issue-triage` (분류 · 중복 제거 · 샤딩 아키텍트)**:
   - 100+개 이슈를 스캔하여 동일 라인/수식 결함에서 파생된 중복 이슈들을 단일 **근본 원인 클러스터(`RCC-001`~`RCC-0NN`)**로 압축합니다.
   - 반드시 **`Tier-DEV`(1순위) → `Tier-AGENT`(2순위) → `Tier-USER`(3순위)** 순서로 실행 큐를 편성합니다.
2. **`dsdx-issue-reproducer` (결정론적 재현기)**:
   - 코드 수정 전에 각 `RCC` 클러스터를 검증하는 회귀 시험을 [platform_e2e_test.py](../tests/platform_e2e_test.py) 또는 [Program.fs](../src/Dsdx.Host/Program.fs)의 `runSelfTest`에 추가하여 재현(`Red`)을 확정합니다.
3. **`dsdx-module-solver` (모듈 샤딩 병렬 해결사)**:
   - 모듈별 소유 파일(`M1: Core.fs`, `M2: Ir.fs`, `M3: Codegen.fs`, `M4: Runtime.fs`, `M5: Aas.fs`, `M6: dsdx_dsd_preselect.py`, `M7: Program.fs`)만 독점 수정하여 병렬 서브에이전트 간 Merge Conflict를 0건으로 유지합니다.
4. **`dsdx-release-gatekeeper` (승격 게이트키퍼)**:
   - 모든 모듈 패치 병합 후 5단계 승격 게이트(`PROMOTE-GATE-5`)를 실행하여 단 하나의 회귀도 허용하지 않습니다.

---

## 5. 정식 버전(`Stable`) vs 실험 버전(`Experimental`) 2-Track MCP 운영 및 승격 전략

외부 클라이언트의 안정적인 운영과 신속한 이슈 패치 검증을 동시에 달성하기 위해 **`https://dualsoft.ai`의 MCP 서비스를 2개 트랙(`stable` / `experimental`)으로 이원화**하여 운영합니다.

### 5.1 2-Track MCP 아키텍처 및 엔드포인트 매트릭스

| 구분 | 정식 트랙 (`Stable` / Production) | 실험 트랙 (`Experimental` / Canary) |
| :--- | :--- | :--- |
| **MCP JSON-RPC 엔드포인트** | **`https://dualsoft.ai/mcp`** | **`https://dualsoft.ai/mcp-exp`** |
| **Host API 엔드포인트** | `https://dualsoft.ai/api/host` | `https://dualsoft.ai/api/host-exp` |
| **웹 스튜디오 엔드포인트** | `https://dualsoft.ai/` (`/play`) | `https://dualsoft.ai/play-exp` |
| **헬스체크 엔드포인트** | `https://dualsoft.ai/healthz` | `https://dualsoft.ai/exp-healthz` |
| **호스트 프로세스 및 내부 포트** | `Dsdx.Host.dll` (`127.0.0.1:8874`, `--channel stable` / 프록시 `ds2mcp`) | `Dsdx.Host.dll` (`127.0.0.1:8875`, `--channel experimental` / 프록시 `ds2mcp-exp`) |
| **권장 사용 대상** | 프로덕션 연동 클라이언트, 정식 PLC 코드젠, HILS/REAL 배포 | `Tier-DEV` 이슈 제보자 패치 즉시 확인, 신규 기능 프리뷰, AI 에이전트 회귀 시험 |

### 5.2 클라이언트 MCP 설정 예시 (`mcp_config.json`)

클라이언트는 필요에 따라 정식 서버(`dsdx-stable`)와 실험 서버(`dsdx-experimental`)를 동시에 등록하거나 전환하여 사용할 수 있습니다.

```json
{
  "mcpServers": {
    "dsdx-stable": {
      "url": "https://dualsoft.ai/mcp"
    },
    "dsdx-experimental": {
      "url": "https://dualsoft.ai/mcp-exp"
    }
  }
}
```

### 5.3 실험 버전(`Experimental`) → 정식 버전(`Stable`) 5단계 승격 게이트 (`PROMOTE-GATE-5`)

모든 코드 수정과 이슈 패치는 **반드시 실험 버전(`https://dualsoft.ai/mcp-exp`)에 먼저 배포**되며, 자동 승격 스크립트([promote_mcp_release.py](../scripts/promote_mcp_release.py))가 아래 **5단계 게이트**를 전수 통과했을 때만 정식 버전(`https://dualsoft.ai/mcp`)으로 블루-그린(Blue-Green) 무중단 승격됩니다.

1. **Gate 1 — F# Core Spine 엄격 빌드**: `dotnet build Dsdx.sln -c Release` (`0 Warnings, 0 Errors`, `FS0025` 불완전 패턴 매칭 0건).
2. **Gate 2 — 코어 스파인 자가검증 및 8-Mutant 하네스**: `Dsdx.Host --self-test` 통과(`Works=9, Mutants=8/8, MCPTools>=28, AAS=COMMITTED, Sandbox=Ver01`; 3D Swept-AABB `Ver02` 및 실기·SILS `Ver03`은 별도 전용 검증 스위트로 분리 기록).
3. **Gate 3 — 정본 명세 및 269 GP 전수 프로브**: `python -X utf8 tests/spec_probe.py` 및 `python -O -X utf8 tests/spec_probe.py` 통과(`BOM=0, CRLF=0`).
4. **Gate 4 — 플랫폼 E2E 및 4대 완전성 기준 검증**: `python -X utf8 tests/platform_e2e_test.py` 통과.
5. **Gate 5 — `mcp-exp` 라이브 카나리 프로브**: `https://dualsoft.ai/mcp-exp` 및 `https://dualsoft.ai/exp-healthz`에 대해 실제 HTTPS JSON-RPC 프로브(`initialize`, `tools/list`, `dsdx.compile`, `dsdx.verify.run`, `dsdx.artifact.export`, `dsdx.aas.sync`, `dsdx.dsd.preselect`)를 수행하여 정상 응답이 확인된 경우에만 `ds2mcp`(`stable`) 컨테이너를 새 이미지로 교체합니다.