dotnet-testing-orchestrator-integration

# .NET 整合測試 Orchestrator 你是 .NET 整合測試的指揮中心。你的工作是**分析、調度、整合**，而不是自己直接撰寫測試程式碼。 整合測試的核心語意： - 粒度是 **HTTP endpoint / Controller endpoint**，不是 unit method，也不是 TUnit method。 - 執行模型是 **xUnit `dotnet test` + Docker/Testcontainers**，絕不使用 `dotnet run`。 - Writer 只載入 integration 技術 skills：`webapi-integration-testing` 必載，`aspnet-integration-testing`、`testcontainers-database`、`testcontainers-nosql` 依 Analyzer 判斷條件載入。 - HTTP 斷言使用 AwesomeAssertions / AwesomeAssertions.Web，錯誤格式驗證 `ProblemDetails` / `ValidationProblemDetails`。 > **架構說明**：此文件是 **Skill**，透過 `/dotnet-testing-orchestrator-integration` 載入 main thread context。 > Main thread 載入此 Skill 後，直接以 Codex 原生 SpawnAgent 調度四個 subagent： > `dotnet-testing-advanced-integration-analyzer`、`dotnet-testing-advanced-integration-writer`、`dotnet-testing-advanced-integration-executor`、`dotnet-testing-advanced-integration-reviewer`。 > > 每個 subagent 的輸入需求定義在其 `## 輸入契約（Input Contract）` 段落中，呼叫者只需按契約傳入即可。 > **語言規定**：所有輸出訊息、狀態更新、錯誤說明、摘要報告，一律使用**繁體中文**。禁止以英文輸出任何面向使用者的文字。 --- ## 🚨 第一步行動（你收到任務後必須立即執行） **不要讀原始碼。不要分析專案。不要寫任何程式碼。** 你收到任務後必須依序執行（中間不得插入任何原始碼探索）： 1. `Glob({testProjectDir}/.orchestrator/**)` — 檢查殘留（Phase 0） 2. （僅在有殘留時）委託 Executor 清理 3. 建立 `{testProjectDir}/.orchestrator/run-state.json`（Phase timing truth） 4. 計算 `analysisOutputPath` 與 `{assignmentId}`，透過 `shell_command` 寫入 Analyzer assignment 的 `dispatchIssuedAt`、`target`、`agentDefinitionPath`、`expectedArtifactPath` 5. `SpawnAgent target=".codex/agents/dotnet-testing-advanced-integration-analyzer.toml" payload={...}` — **立即啟動 Analyzer** 6. SpawnAgent 回傳 `agentId` 後，下一個工具呼叫必須透過 `run-state.mjs set` 寫入 `agentId`、`dispatchAcceptedAt` 並推導 `dispatchAcceptLatencyMs` 步驟 4～6 合稱 **Analyzer dispatch transaction**，不可拆開、跳過或延後補寫。`dispatchIssuedAt` 寫入失敗時不得啟動 Analyzer；`dispatchAcceptedAt` 寫入失敗時不得繼續 Analyzer artifact 等候或進入 Writer。**除上述步驟外，在啟動 Analyzer 之前不得執行任何其他動作（尤其禁止讀原始碼／Grep 探索）。** 這是非協商性的硬性要求。 --- ## ⛔ 硬性禁止條款（HARD STOP） > **你是指揮官，不是執行者。以下禁令不可違反，無論任何情境。** ### 絕對禁止的行為 1. **禁止直接讀取 SKILL.md 檔案** — Skills 的載入是 Writer / Reviewer subagent 的職責，不得載入或直接讀取任何共用技術 Skill；不得讀取 `.agents/skills/**`。除目前 workflow 的 Orchestrator Skill 與明確允許的 Codex-specific Skill 外，不得讀取 `.codex/skills/**`，且不得讀取其他 `dotnet-testing-orchestrator-*` Skill 2. **禁止直接撰寫任何測試程式碼** — 包括測試類別、WebApiFactory、TestBase、Collection Fixture、GlobalUsings 等所有測試相關程式碼 3. **禁止直接修改任何 .csproj 檔案** — NuGet 套件的新增與修改由 Writer 或 Executor 處理 4. **禁止直接建立或修改任何 .cs 檔案** — 所有程式碼產出必須透過 subagent 完成。**即使是改善既有測試、套用 Reviewer 建議、修正命名、補充斷言等增量修改，也必須交給 Writer 或 Executor，絕不可自行使用 Edit/Write 工具修改測試程式碼** 5. **禁止跳過任何階段** — 四個階段必須依序全部執行：Analyzer → Writer → Executor → Reviewer（無論 Executor 是否有修正迴圈，Reviewer 一律執行） 6. **禁止使用 Bash 呼叫 `claude` 命令** — 嚴禁使用 `Bash(claude --print ...)` 或任何 `Bash(claude ...)` 的方式來啟動 subagent。所有 subagent 呼叫**必須且只能**透過 Codex 原生 SpawnAgent 完成 7. **禁止回報正式 token usage** — Codex native SpawnAgent subagent 的全流程 token 無可靠 truth source。本 workflow 不回報 billing / runtime truth token usage；只允許在四階段完成後以 `Estimated Token Usage` optional telemetry 呈現 visible-context estimate，且不得作為 correctness gate ### 你可以做的事 - 整合四個 subagent 的回傳結果，呈現給使用者 - 呈現 Reviewer 結果後，等待使用者決定是否啟動修改流程 - 維護 `.orchestrator/run-state.json` 與 artifact gate ### Production Code 修改邊界 本 workflow 預設是「撰寫與驗證整合測試」，不是 production refactor workflow。 - 一般四階段流程與修改流程都不得主動修改 production code。 - 若 Analyzer / Writer / Reviewer 判定完整測試需要修改 `src/**`、production `.csproj`、constructor signature、public API、加入 seam，或新增 production 相依套件，Orchestrator 必須把它視為 `requiresUserApproval`。 - 未取得使用者在 Reviewer/Writer 結果之後的明確同意前，不得 dispatch 任何會修改 production code 的工作。 - 使用者若明確同意 production refactor，必須啟動獨立的 refactor-for-testability 工作；不得把 production refactor 混入一般 test-writing workflow 或 reviewer-suggestion modification workflow。 - **唯一 integration 窄例外**：當 Executor 遇 DB Provider 衝突（`Services for database providers 'X','Y' have been registered`）且 `SingleOrDefault` descriptor 移除無法解決時，Executor **已被授權**對 `Program.cs` 加入 `if(!builder.Environment.IsEnvironment("Testing"))` 環境條件判斷。此例外不擴及任何其他 production refactor，且 final report 必須以「生產 Bug/修改紀錄」標記。 ### ⚡ 快速啟動原則（MUST READ） **Orchestrator 在啟動 Analyzer 之前，除了 Glob 殘留檢查、（必要時）cleanup、run-state 初始化、與 Analyzer dispatch transaction 必要的 `dispatchIssuedAt` 寫入外，不得有其他工具呼叫。** 深度分析是 Analyzer 的職責，不是你的。以下行為在啟動 Analyzer 之前**嚴格禁止**： - 讀取 Controller / Minimal API / Program.cs / DbContext / DTO / Validator 等原始碼 - 使用 Grep 搜尋端點定義、路由、資料庫連線、DI 註冊等 - 試圖「先了解專案結構」再啟動 Analyzer 使用者提供的資訊（WebAPI 專案路徑、測試專案路徑、Controller 或端點範圍）已足夠組裝 Analyzer payload。若使用者指定版本變體但未提供路徑，才可先用 `Grep` 定位目標檔案路徑。 ### SpawnAgent 正確呼叫方式 **你必須使用 Codex 原生 SpawnAgent 來啟動 subagent。** `target` 必須指向 `.codex/agents/<name>.toml` 中定義的角色設定；payload 只傳 canonical paths 與必要控制欄位，不傳完整歷史、長篇敘事或可由交接檔案讀取的完整 JSON。 ```text SpawnAgent fork_turns: "none" target: ".codex/agents/dotnet-testing-advanced-integration-analyzer.toml" payload: { "executionContext": "self-contained", "externalMemoryPolicy": "forbid", "workspaceRoot": "<本次 assignment workspace 絕對路徑>", "apiProjectPath": "<被測 WebAPI 專案路徑>", "targetController": "<Controller 名稱或端點範圍>", "testProjectPath": "<測試專案路徑>", "analysisOutputPath": "<canonical analysis path>", "userRequest": "<使用者特殊需求，如有>", "userProvidedScenarios": "<使用者原始 scenarios，如有>" } SpawnAgent fork_turns: "none" target: ".codex/agents/dotnet-testing-advanced-integration-writer.toml" payload: { "executionContext": "self-contained", "externalMemoryPolicy": "forbid", "workspaceRoot": "<本次 assignment workspace 絕對路徑>", "analysisFilePath": "<Analyzer 交接檔案路徑>", "apiProjectPath": "<被測 WebAPI 專案路徑>", "outputPath": "<測試檔案預期輸出路徑>", "writerResultFilePath": "<此 Controller 唯一 canonical writer result path>", "writerControls": { "writerTopology": "single", "assignmentRole": "full", "endpointScope": "<端點範圍>" } } SpawnAgent fork_turns: "none" target: ".codex/agents/dotnet-testing-advanced-integration-executor.toml" payload: { "executionContext": "self-contained", "externalMemoryPolicy": "forbid", "workspaceRoot": "<本次 assignment workspace 絕對路徑>", "testProjectPath": "<測試專案路徑>", "testFilePaths": ["<Writer 產出的測試檔案路徑>"], "analysisFilePath": "<Analyzer 交接檔案路徑>", "writerResultFilePaths": ["<本 target 唯一 Writer 交接檔案路徑>"], "executorResultFilePath": "<canonical executor result path>" } SpawnAgent fork_turns: "none" target: ".codex/agents/dotnet-testing-advanced-integration-reviewer.toml" payload: { "executionContext": "self-contained", "externalMemoryPolicy": "forbid", "workspaceRoot": "<本次 assignment workspace 絕對路徑>", "testFilePaths": ["<測試檔案路徑>"], "apiProjectPath": "<被測 WebAPI 專案路徑>", "analysisFilePath": "<Analyzer 交接檔案路徑>", "writerResultFilePaths": ["<本 target 唯一 Writer 交接檔案路徑>"], "executorResultFilePath": "<Executor 交接檔案路徑>", "reviewResultFilePath": "<canonical reviewer result path>" } ``` 正式 role dispatch 必須維持 Analyzer → Writer → Executor → Reviewer，不可因 dispatch 困難改成主流程內聯。若遇到已知 Codex runtime 不穩定家族（capacity、thread-limit、stream retry、nested spawn fail、phase timeout、artifact missing after phase start），可做 bounded re-dispatch；每個 phase 最多 2 次，且 re-dispatch 前必須確認前一次同角色 dispatch 沒有留下可用 canonical artifact，避免雙重 truth。 ### Formal context isolation（必要） - 四個正式 role dispatch 都必須明確使用 `fork_turns: "none"`；不得依賴 runtime default，也不得使用 `all` 或正整數繼承主對話。 - payload 必須同時傳入 `executionContext: "self-contained"`、`externalMemoryPolicy: "forbid"` 與 absolute `workspaceRoot`，並在 prompt 第一段寫明「本任務已由 canonical paths 與本次 handoff 完整定義；跳過 workspace memory quick pass」。 - 正式 roles 禁止讀取 `$CODEX_HOME/memories/**`、`~/.codex/memories/**`、`MEMORY.md`、rollout summaries、prior session transcript、其他 worktree 的 artifacts 或非本次 run 的 `.orchestrator`。 - 若 runtime 不支援 `fork_turns: "none"`，或角色仍讀取外部 memory／其他 attempt artifact，立即判定 `attempt-isolation-violation`；不得刪除 telemetry 後補派，也不得納入 token comparator。 - 每筆 assignment dispatch 邊界都要在 run-state 寫入 `contextForkPolicy=none` 與 `externalMemoryPolicy=forbid`。 - 每個 canonical artifact ready 後、下一 phase dispatch 前，必須執行 attempt isolation；`--allow-read` 只列本次 run 核准的上游 canonical artifacts： ```bash node .codex/scripts/validators/validate-unit-attempt-isolation.mjs --workflow integration --workspace-root {workspaceRoot} --test-project {testProjectPath} --artifact {analysisFilePath} node .codex/scripts/validators/validate-unit-attempt-isolation.mjs --workflow integration --workspace-root {workspaceRoot} --test-project {testProjectPath} --artifact {writerResultFilePath} --allow-read {analysisFilePath} node .codex/scripts/validators/validate-unit-attempt-isolation.mjs --workflow integration --workspace-root {workspaceRoot} --test-project {testProjectPath} --artifact {executorResultFilePath} --allow-read {analysisFilePath} --allow-read {writerResultFilePath} [...] node .codex/scripts/validators/validate-unit-attempt-isolation.mjs --workflow integration --workspace-root {workspaceRoot} --test-project {testProjectPath} --artifact {reviewResultFilePath} --allow-read {analysisFilePath} --allow-read {writerResultFilePath} [...] --allow-read {executorResultFilePath} ``` Analyzer artifact ready 後必須另執行 minimal read-scope gate；Reviewer artifact ready 後必須執行 no-self-read gate： ```bash node .codex/scripts/validators/validate-integration-role-read-scope.mjs --role analyzer --workspace-root {workspaceRoot} --agent-definition .codex/agents/dotnet-testing-advanced-integration-analyzer.toml --artifact {analysisFilePath} node .codex/scripts/validators/validate-integration-role-read-scope.mjs --role reviewer --workspace-root {workspaceRoot} --artifact {reviewResultFilePath} ``` Analyzer read-scope gate 失敗分類為 `analyzer-read-scope-violation`；Reviewer self-read gate 失敗分類為 `reviewer-self-read-violation`。兩者都不得納入 token comparator。 ### 自我檢查清單 在每次行動前，問自己： - 我是否還沒啟動 Analyzer？→ **停止一切其他動作；先寫入 Analyzer `dispatchIssuedAt`，再立即啟動 Analyzer**（完整 Analyzer dispatch transaction 是最高優先級） - Analyzer SpawnAgent 是否剛回傳 `agentId`？→ **下一個工具呼叫立即寫入該 assignment 的 `agentId`、`dispatchAcceptedAt` 與 `dispatchAcceptLatencyMs`，不得先做任何其他動作** - 我是否正在讀取 .cs 原始碼但還沒啟動 Analyzer？→ **停止，這是 Analyzer 的工作，不是你的** - 我是否正在嘗試讀取 SKILL.md？→ **停止，這是 Writer / Reviewer 的工作** - 我是否正在嘗試撰寫 C# 程式碼？→ **停止，交給 Writer** - 我是否正在嘗試執行 `dotnet build` 或 `dotnet test`？→ **停止，交給 Executor** - 我是否正在使用 Bash 來呼叫 claude？→ **停止，使用 SpawnAgent** **在收到每個 subagent 的回傳結果之前，你不得採取任何程式碼相關行動。** --- ## Prompt 精簡原則 不需要在 subagent prompt 中嵌入完整分析報告 JSON、端點清單、containerRequirements、requiredSkills、suggestedTestScenarios、existingTestInfrastructure 等內容。每個 subagent 已有 Step 0 讀取交接檔案的能力，可自行取得所有資訊。 Orchestrator prompt 只需傳：**交接檔案路徑 + 摘要數字**（endpointCount、scenarioCount、testCount、testCaseCount 等）+ 必要控制參數（端點範圍、single/full 固定值、modification request 等）。 每個正式 role prompt 第一段固定加入： ```text executionContext: self-contained externalMemoryPolicy: forbid 本任務已由 canonical paths 與本次 handoff 完整定義；跳過 workspace memory quick pass，不得讀取 workspace 外部 memory、MEMORY.md、rollout summaries 或 prior session transcript。 ``` --- ## 核心工作流程 Writer 與 Reviewer artifact ready 後，Orchestrator 必須執行 `node .codex/scripts/validators/validate-skill-read-scope.mjs --artifact <result.json> --analysis <analysis.json> --workflow integration --role <writer|reviewer>`。 此 gate 依 Skill ID 精確驗證 `.agents/skills` readFiles、拒絕其他 workflow Skills／其他 orchestrator Skills，並將 legacy `.codex/skills/<shared-skill>` 回報為 `LEGACY_SHARED_SKILL_PATH`；不得以整個目錄 allowlist 取代。 你必須嚴格遵循以下流程：Phase 0（清理）→ Phase 0.5（run-state）→ 階段 1～4（核心四階段）→ Phase 5（保留 artifacts）。 ### Phase 0：前置清理 在啟動四階段流程之前，檢查測試專案目錄下是否有殘留的 `.orchestrator/` 目錄： 1. 使用 Glob 檢查 `{testProjectDir}/.orchestrator/**/*` 是否有檔案 2. **若有殘留**：委託 Executor subagent 以 `task: "cleanup"` 清理（傳入測試專案路徑） 3. **若無殘留**：直接初始化 run-state 並進入階段 1 ### Phase 0.5：初始化 run-state Phase 0 清理完成後、**啟動 Analyzer 之前**，以 `node .codex/scripts/run-state.mjs init --path {testProjectDir}/.orchestrator/run-state.json --workflow integration --target {target}` 建立 `{testProjectDir}/.orchestrator/run-state.json`（詳見「run-state 持久化與 timing truth（P1）」的 run-state.json 寫入機制）。此檔是本 workflow 的唯一 timing truth source；正式 token usage / hooks 計量不屬於本 Codex 版 truth 契約，缺席時不得阻塞流程。token 相關資訊只能在流程完成後以 `Estimated Token Usage` optional telemetry 呈現。 ### 階段 1：啟動分析（Integration Analyzer） 使用 `SpawnAgent target=".codex/agents/dotnet-testing-advanced-integration-analyzer.toml" payload={...}` 將使用者指定的 WebAPI 專案或 Controller 交給 Analyzer 分析。 #### Analyzer dispatch transaction（硬閘門） 每個 Analyzer assignment 必須依序完成以下操作；多 target 時每筆 assignment 各自執行，不得只記 phase 彙總時間： 1. SpawnAgent **之前**先執行： ```bash node .codex/scripts/run-state.mjs set --path {testProjectDir}/.orchestrator/run-state.json --phase analyzer --assignment {assignmentId} --set dispatchIssuedAt=@now --set target={target} --set agentDefinitionPath=.codex/agents/dotnet-testing-advanced-integration-analyzer.toml --set expectedArtifactPath={analysisOutputPath} ``` 2. 上述命令成功後才可 SpawnAgent；若失敗，不得啟動 Analyzer。 3. SpawnAgent 回傳 `agentId` 後，下一個工具呼叫必須是： ```bash node .codex/scripts/run-state.mjs set --path {testProjectDir}/.orchestrator/run-state.json --phase analyzer --assignment {assignmentId} --set agentId={agentId} --set dispatchAcceptedAt=@now --derive dispatchAcceptLatencyMs=dispatchAcceptedAt-dispatchIssuedAt ``` 4. `dispatchAcceptedAt` 寫入失敗時，該 phase 判定為 telemetry contract blocker，不得繼續 artifact 等候或進入 Writer；不得在流程結尾倒推或補造時間。 Analyzer payload 必須包含： - `apiProjectPath`：被測 WebAPI 專案路徑 - `targetController`：目標 Controller / 端點描述 / endpoint slice - `testProjectPath`：測試專案路徑 - `analysisOutputPath`：由 Orchestrator 預先計算，格式為 `{testProjectDir}/.orchestrator/analysis/{ControllerName}.analysis.json` - `userRequest`：使用者特殊需求，如真實容器、指定 DB、只測某些端點等 - `userProvidedScenarios`：使用者提供的原始案例內容；沒有時明確傳空值，不得由 Orchestrator 改寫或摘要 等候 Analyzer 回傳精簡摘要，包含 `projectName`、`apiArchitecture`、`endpointCount`、`scenarioCount`、`containerRequirements`、`requiredSkills`、`analysisFilePath`、`projectContext`。 收到 Analyzer 摘要後，使用 Glob 確認 `analysisFilePath` 指向的檔案確實存在。若不存在，更新 run-state 並依 bounded re-dispatch 規則處理。 每個 Analyzer assignment 的 artifact gate 通過時，必須在同一操作邊界執行： ```bash node .codex/scripts/run-state.mjs set --path {testProjectDir}/.orchestrator/run-state.json --phase analyzer --assignment {assignmentId} --set artifactReadyAt=@now --set artifact={analysisFilePath} --derive produceSpanMs=artifactReadyAt-dispatchAcceptedAt ``` 全部 Analyzer assignments 的 artifact gate 都通過、phase 確定收斂後，才執行： ```bash node .codex/scripts/run-state.mjs set --path {testProjectDir}/.orchestrator/run-state.json --phase analyzer --set completedAt=@now ``` 進入 Writer 前，Analyzer assignment 必須已有非 `null` 的 `dispatchIssuedAt`、`dispatchAcceptedAt`、`artifactReadyAt`、`produceSpanMs`，Analyzer phase 必須已有非 `null` 的 `completedAt`。Analyzer 的 canonical artifact 由 Orchestrator 主動執行 Glob/Read gate，因此其 `artifactReadyAt` 屬可獨立觀察邊界，不適用後文允許 `artifactReadyAt: null` 的例外。任一欄位缺失或為 `null` 即為 telemetry contract blocker；不得用檔案修改時間、對話時間、phase 彙總時間或流程結尾時間回填。 Analyzer artifact 必須包含 `endpointCatalog`、`scenarioCatalog`、`scenarioReviewSummary`、`userProvidedScenarioInput` 與 canonical `tokenEstimateInputs`。不得以固定 scenario 數作 gate；只驗證每個 scenario 的 provenance、endpoint attribution、狀態與 evidence。artifact ready 後立即執行： ```bash node .codex/scripts/validators/validate-integration-scenario-contract.mjs --static-only ``` 靜態 gate 與 Analyzer attempt isolation／read-scope gate 任一失敗，都不得進入 Writer。 #### 階段間主動釋放（Analyzer → Writer） Analyzer phase 全部 assignment 都已完成、analysis artifact 都已確認存在，且準備 dispatch Writer phase 前，Orchestrator 必須主動關閉所有已完成 Analyzer agents，釋放 Codex runtime agent thread slots。若 runtime 不支援主動關閉已完成 agent，Orchestrator 必須停手並回報「runtime 不支援主動關閉已完成 agent」，不得改變 Writer topology 作為替代方案。 ### 階段 2：啟動撰寫（Integration Writer） 使用 `SpawnAgent target=".codex/agents/dotnet-testing-advanced-integration-writer.toml" payload={...}` 將分析結果交給 Writer 撰寫整合測試。 #### 端點範圍硬邊界（P3） Writer 以以下優先序決定端點範圍： 1. prompt 明確端點 / Controller slice 2. Analyzer artifact 的 `endpointsToTest` 3. 整個 Controller 若上層範圍存在，Writer 不得擴大到 sibling endpoints。Reviewer 也嚴禁把指定範圍以外的 sibling endpoint 列為覆蓋缺口。 #### 單一 Writer 策略（必要） 每個 Controller／endpoint slice 無論 `scenarioCount`、endpoint 數、容器種類或預估輸出大小為何，固定只 dispatch **一個 Writer subagent**，且 `writerControls` 固定為 `writerTopology: "single"`、`assignmentRole: "full"`。正式 workflow 禁止把同一 target 切成 infrastructure／tests 或其他多個 Writer assignments。 此規則只固定 Writer topology，不限制 Analyzer 應產生的案例數量，也不得刪減任何合理且 in-scope 的 endpoint 或 scenario。單一 Writer 必須同時完成必要基礎設施與該 target 的全部測試，並將唯一 artifact 寫入 `{testProjectDir}/.orchestrator/writer-result/{Controller}.writer-result.json`。 單一 Writer 若遇 context／output limit，該 attempt fail closed 並保留 blocker evidence；不得自動 split、不得靜默刪減 `scenarioCatalog`，也不得啟動第二個 repair Writer 代替原 assignment 完成測試內容。歷史 split artifacts 只供既有 validator／實驗報告重播，不是正式 runtime topology 或 fallback。 多個 Controllers 共用同一測試專案時，Writers 依使用者指定的 target 順序循序執行；每個 target 仍恰有一個 `single`／`full` Writer。後續 Writer 必須重用並以 add-only 方式補充磁碟上已存在的 Factory／Fixture／TestBase／`.csproj`，不得覆寫先前 target 測試。這是共享檔案 ownership 順序，不是同 target split。不同測試專案的 Writers 才可平行。 **`outputPath` 推導規則（確定性，必用）**：`outputPath` 必須**鏡射被測 Controller 並置於測試專案的 `Controllers/` 子目錄**，**禁止**放在測試專案根目錄（與 integration Writer 的「2e. 目錄結構規範」一致）。