path: root/plans/ImplementationPlan.md

# AI Agent Sandbox MCP Server — 実装・監査作業計画
**文書名:** `ImplementationPlan.md`  
**版:** 0.1 Draft  
**上位文書:** `Specifications.md` / `Design.md`  
**目的:** Codex等のAIコーディングエージェントへ実装作業を委任しつつ、各段階の成果・差分・テスト・未完了事項を後から人間が監査できる形で管理する。
---
## 1. 文書の位置付け
### 1.1 文書間の優先順位
実装判断の優先順位を次に固定する。
1. `Specifications.md`
2. `Design.md`
3. `ImplementationPlan.md`
4. 実装コード・テスト・設定
5. Codexの作業上の判断
下位成果物が上位文書と矛盾する場合、下位成果物を修正する。実装都合で仕様を暗黙変更してはならない。
### 1.2 本計画の役割
本計画は次を定義する。
- 実装フェーズと依存順序
- 各フェーズの実装対象と非対象
- 完了条件
- 必須テスト
- Codexが提出すべき監査証跡
- 人間が後から確認する監査観点
- 次フェーズへ進むためのGate
- 仕様変更が必要になった場合の停止条件
### 1.3 本計画が定義しないもの
以下は上位文書または実装時の詳細設計に従う。
- 仕様そのものの変更
- Security Invariantの緩和
- 新しいMCP Toolの追加
- Windows APIの具体的なAPI呼出し系列のうち `Design.md` で実装時選択としている部分
- 未承認依存ライブラリの追加
---
## 2. 実装・監査の基本原則
| ID | 原則 | 内容 |
| --- | --- | --- |
| PLAN-01 | Traceability | すべての実装項目を仕様ID・設計章・テストへ結び付ける。 |
| PLAN-02 | Evidence First | 「実装した」という報告だけを完了根拠にしない。コード、テスト結果、ログ等の証跡を要求する。 |
| PLAN-03 | Small Change | 1フェーズ内でも責務単位の小さい変更に分割する。 |
| PLAN-04 | No Silent Scope Growth | Codexが独自に機能・層・ライブラリ・MCP Toolを増やすことを禁止する。 |
| PLAN-05 | Security Gate | Security Invariantに関係する失敗を残したまま後続フェーズへ進まない。 |
| PLAN-06 | Deterministic Verification | Policy、Planner、State Transition等はLLM評価ではなく自動テストで確認する。 |
| PLAN-07 | Negative Test | セキュリティ機能は成功ケースだけでなく拒否ケースを必須とする。 |
| PLAN-08 | Recovery Test | ACL/WFP/File transaction等の一時副作用は異常終了からの回復まで検証する。 |
| PLAN-09 | No Hidden Completion | TODO、stub、skip、未実行テストを残した状態をPASSと報告しない。 |
| PLAN-10 | Auditability | 各Gateで、第三者が再実行できるコマンドと結果を保存する。 |
---
## 3. Codex提出物の共通形式
各フェーズ完了時にCodexは以下を提出する。
### 3.1 必須作業報告
```markdown
## Phase <n> Completion Report

### 実施内容
- ...

### 変更ファイル
- path/to/file: 変更理由

### 対応Requirement / Design
- Requirement: ...
- Design section: ...

### 実行した検証
- command: `...`
- result: PASS / FAIL
- summary: ...

### 新規・更新テスト
- test name: 対象

### 監査証跡
- build log: ...
- test log: ...
- audit/security log: ...

### 未完了・既知問題
- None / ...

### 仕様・設計からの逸脱
- None / ...

### 次フェーズへの前提
- ...
```
### 3.2 必須証跡
| 証跡 | 必須 | 内容 |
| --- | :---: | --- |
| Git diff / commit | Yes | そのフェーズの変更範囲を特定できること。 |
| Build結果 | Yes | `dotnet build` の成功。 |
| Test結果 | Yes | 対象unit/integration testの件数と結果。 |
| 新規テスト一覧 | Yes | 追加したテスト名と対応仕様。 |
| Skip一覧 | Yes | 0件であることを原則とする。存在する場合は理由を明記。 |
| TODO/FIXME一覧 | Yes | 新規に残したものを列挙。 |
| Dependency差分 | Yes | NuGet追加・更新がないこと、または承認根拠。 |
| Security evidence | 該当時 | deny結果、cleanup結果、process tree等。 |
| Audit Log sample | 該当時 | 仕様どおりのeventが出ていること。 |
### 3.3 禁止する完了根拠
以下だけでは完了と認めない。
- 「コードを確認したので問題ない」
- 「コンパイルできるはず」
- 「既存テストは影響しない」
- 「手元ではおそらく動作する」
- LLM自身によるコードレビューのみ
- テストを実行していない状態でのPASS宣言
---
## 4. 全体フェーズ
| Phase | 名称 | 主成果 | Gate |
| ---: | --- | --- | --- |
| 0 | Baseline / Skeleton Lock | solution、依存、CI相当のローカル検証基盤 | G0 |
| 1 | Configuration / Localization / Logging | YAML、locale、固定Prompt基盤 | G1 |
| 2 | MCP Public Interface | stdio、非同期Task受付、`agent_run/status` | G2 |
| 3 | Session / Ollama / Prompt | text会話、Session、token usage、Prompt優先順位 | G3 |
| 4 | Token Planner | TaskGraph、Token PERT/CPM、再計画 | G4 |
| 5 | Internal Tool / Policy Boundary | 5 Internal Tool、ToolUseGuard、Policy Engine | G5 |
| 6 | Filesystem / Process Sandbox | AppContainer、ACL、Job、hash approval | G6 |
| 7 | Transaction / Recovery | ACL Resource Transaction、File rollback、Recovery Journal | G7 |
| 8 | Network Sandbox | WFP deny / host-port allow-list | G8 |
| 9 | Vision / Streamable HTTP | optional画像、loopback HTTP | G9 |
| 10 | Audit / Security Hardening | Audit JSONL、全Security Matrix | G10 |
| 11 | Acceptance / Release Audit | AT全件、文書整合、未完了ゼロ確認 | G11 |
依存順は原則として `0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11` とする。
Security境界を後回しにした状態で、実際の任意Process実行を先行実装してはならない。
---
# 5. Phase 0 — Baseline / Skeleton Lock
## 5.1 目的
実装開始前にsolution構造、ビルド、テスト、依存追加ルールを固定し、以降の差分を監査可能にする。
## 5.2 実装対象
- .NET 10 / C# 14 solution
- `Agent.App`
- `Agent.Mcp`
- `Agent.Core`
- `Agent.Planner`
- `Agent.Windows`
- 対応Test project
- `Directory.Build.props` 等の共通設定
- warning方針
- Git ignore
- 最小README
- `ollama --version` の実測baseline証跡
- v1単一実行キュー（複数queued、planning/running/Task Resource適用は全体で最大1件）
## 5.3 非対象
- MCP実処理
- Ollama通信
- Sandbox実装
- Planner実装
## 5.4 完了条件
- [ ] `dotnet restore` 成功
- [ ] `dotnet build` 成功
- [ ] `dotnet test` 成功
- [ ] Project dependencyが `Design.md` の方向と一致
- [ ] `Agent.Core` / `Agent.Planner` がWin32型を参照していない
- [ ] 不要なProject・Utility層が作成されていない
- [ ] 未承認NuGet dependencyがない
## 5.5 必須監査
| 監査 | 確認内容 |
| --- | --- |
| Project graph | Design 4章と一致するか |
| Package list | 許可されたpackageだけか |
| Build | warning/errorの状態 |
| Naming | `Utils/Common/Infrastructure/Manager`等の曖昧な巨大層がないか |
### Gate G0
全完了条件PASS。構造上の逸脱がある場合はPhase 1へ進まない。
---
# 6. Phase 1 — Configuration / Localization / Logging
## 6.1 対応仕様
- Specifications 14章、15章、16章
- I18N-01〜11
- NFR-05、NFR-08、NFR-09
## 6.2 実装対象
- `agent.yaml`
- `schema_version`
- typed configuration
- `en.json` / `ja.json`
- locale loader / validator
- named placeholder
- CLI `--config` / `--lang`
- fallback `selected locale → en → key`
- Fixed System Promptの埋め込み基盤
- User System Prompt path
- Application Logのstderr/file基盤
## 6.3 重要制約
- Fixed System Promptを外部ファイルへ移動しない。
- locale messageをコード中に直接ハードコードしない。
- unknown locale keyまたは壊れたJSONはfatal。
- Hot Reloadを実装しない。
## 6.4 必須テスト
- [ ] `en` 起動
- [ ] `ja` 起動
- [ ] `--lang` がconfigより優先
- [ ] 追加locale fileをコード変更なしで読める
- [ ] missing keyはfallbackする
- [ ] unknown keyでfatal
- [ ] malformed JSONでfatal
- [ ] placeholder不一致でfatal
- [ ] invalid YAML/schemaでfatal
## 6.5 監査証跡
- locale key一覧比較結果
- `agent-mcp check --lang en/ja` の結果
- stderr/file log sample
- Fixed Promptの格納場所
### Gate G1
LocalizationとConfigurationのnegative testを含め全PASS。
---
# 7. Phase 2 — MCP Public Interface
## 7.1 対応仕様
- MCP-TR-01〜05
- MCP-RUN-01〜05
- MCP-STS-01〜02
- AT-01〜05
- SEC-INV-12
## 7.2 実装対象
- MCP公式C# SDK
- stdio transport
- public Toolを `agent_run` / `agent_status` の2個だけ登録
- 非同期Task受付の最小Task registry
- UUID Task ID / Session ID
- `agent_run` Schema
- `agent_status` Schema
- text content response
- optional `temperature`
## 7.3 このPhaseではstubでよい部分
Agent本体はまだ未実装のため、Task workerは決定的なstubでもよい。ただしMCP I/Fと状態遷移の外形を固定する。
## 7.4 必須テスト
- [ ] initialize成功
- [ ] tool listが2個のみ
- [ ] `agent_run` がblockingせずTask ID/Session IDを返す
- [ ] `agent_status` がTaskを取得できる
- [ ] invalid schemaを拒否
- [ ] model/system prompt/policyを指定する余分なpropertyを拒否
- [ ] stdio stdoutにMCP protocol以外が出ない
- [ ] Legacy SSE endpointが存在しない
## 7.5 監査ポイント
Codexが「便利な補助MCP Tool」を追加していないことを明示確認する。
### Gate G2
MCP surfaceが仕様どおり2 Toolのみで固定されていること。
---
# 8. Phase 3 — Session / Ollama / Prompt
## 8.1 対応仕様
- OLL-01〜13
- SES-01〜06
- Specifications 10章
## 8.2 実装対象
- Ollama `HttpClient`
- Chat API
- typed `OllamaOptions`
- `extra_options`
- temperature Task-scope override
- `prompt_eval_count` / `eval_count`
- in-memory Session Store
- Conversation / ExecutionResults
- Prompt Composer
- Prompt優先順位
- Ollama transient retry 3回
## 8.3 Prompt順序
1. Fixed System Prompt
2. User System Prompt
3. Locale instruction
4. Skill
5. Sandbox capability summary
6. TaskGraph / current Task
7. Summary
8. Conversation / Execution Result
このPhaseではSkill選択やTaskGraphが未実装の場合、空要素として合成可能にする。
## 8.4 必須テスト
- [ ] text-only Ollama call成功
- [ ] Session継続でconversationが保持される
- [ ] process再起動後Sessionが消失する
- [ ] temperature overrideが当該Taskだけに作用
- [ ] typed optionと`extra_options`競合時にtyped optionが優先される
- [ ] prompt/eval tokenを取得
- [ ] transient errorだけ最大3回retry
- [ ] permanent errorを無駄にretryしない
- [ ] Fixed PromptをUser Promptが置換できない
## 8.5 監査証跡
- 実際にOllamaへ送信したpayloadのsanitized sample
- token usage sample
- Session IDを跨いだ2回以上の会話テスト
### Gate G3
Ollama通信とSessionがMCP I/Fに統合され、global設定をTaskから変更できないこと。
---
# 9. Phase 4 — Token Planner
## 9.1 対応仕様
- PLN-01〜06
- Specifications 8章
- AT-14〜17
## 9.2 実装対象
- `AgentTask`
- `TaskGraph`
- DAG validation
- max_tasks=32
- completed immutable
- Token Budget Class 1K〜128K
- O/M/P Token PERT
- Token CPM
- Task追加 / dependency追加
- 実測input/output/total token
## 9.3 不変条件
```text
0 < O <= M <= P <= TokenBudgetClass.MaxTokens
ExpectedTokens = (O + 4M + P) / 6
TaskGraph is DAG
completed Task is immutable
```
## 9.4 必須テスト
- [ ] cycle拒否
- [ ] max_tasks超過拒否
- [ ] completed変更拒否
- [ ] O/M/P invalid ordering拒否
- [ ] Budget超過拒否
- [ ] 既知DAGでcritical path一致
- [ ] graph変更でCPM再計算
- [ ] Ollama実測tokenがTaskへ累積
## 9.5 監査
Known-answer testを用意し、LLMを使わず同一入力で同一結果になることを確認する。
### Gate G4
Planner deterministic test全PASS。
---
# 10. Phase 5 — Internal Tool / Policy Boundary
## 10.1 対応仕様
- AGT-01〜06
- OLL-10〜11
- SEC-INV-01〜02
## 10.2 Internal Toolを5群に固定
| Tool | Operation |
| --- | --- |
| `file_search` | glob / name / text / regex / tail |
| `file_read` | whole / range / metadata |
| `file_edit` | overwrite / patch / atomic_replace / delete |
| `process_run` | exe + args + cwd + timeout |
| `task_update` | add / dependency / state / estimate |
個々の `grep`、`find`、`tail` 等を独立Toolにしない。
## 10.3 実装対象
- JSON Schema
- Ollama native tool calling
- Internal Tool Dispatcher
- Policy Engine I/F
- Tool argument validation
- ToolUseGuard
- `requires_external_effect`
- same failure fingerprint limit=5
## 10.4 重要な段階制約
このPhaseの副作用backendはfake/in-memory実装を使用可能とし、Windows sandboxを迂回した本物の無制限file/process操作を実装してはならない。
## 10.5 必須テスト
- [ ] MCP ClientからInternal Toolが見えない
- [ ] Ollamaには5群のみ公開
- [ ] malformed tool args拒否
- [ ] Policy deny時に副作用なし
- [ ] Policy denyは初回でfailedとなり、LLMへ再試行されない
- [ ] external effect必須Taskでtool未使用ならcompletedにならない
- [ ] 同一失敗5回でfailed
- [ ] pure analysis TaskにはToolを強制しない
### Gate G5
LLM→Tool→Policyの境界が固定され、Policyを通らない副作用経路が存在しないこと。
---
# 11. Phase 6 — Filesystem / Process Sandbox
## 11.1 対応仕様
- Specifications 11.1〜11.3
- SEC-INV-03〜05、08
- ST-01〜11、ST-16
## 11.2 実装対象
- Application固定AppContainer Profile
- Sandbox Broker
- FilesystemPolicy R/W/E/Delete
- canonical path
- reparse point防御
- NTFS ACL（承認directory rootへの継承ACE、root単位snapshot、protected descendantのfail-safe維持）
- Process approval canonical path + SHA-256
- shell toggle
- Job Object
- descendant制御
- process count / memory limit
- KILL_ON_JOB_CLOSE
- Named Pipeが必要ならtask固有DACL
## 11.3 Process approval
承認条件は以下を両方満たすこと。
```text
canonical path == approval.path
SHA-256        == approval.sha256
```
hash変更、path変更は再承認を必要とする。
## 11.4 必須Security Test
- [ ] ST-01 read許可成功
- [ ] ST-02 read未許可拒否
- [ ] ST-03 write許可成功
- [ ] ST-04 delete権限なし拒否
- [ ] ST-05 junction脱出拒否
- [ ] ST-06 symlink chain脱出拒否
- [ ] ST-07 approved exe成功
- [ ] ST-08 hash mismatch拒否
- [ ] ST-09 shell disabled拒否
- [ ] ST-10 descendant未承認exe拒否
- [ ] ST-11 Job closeで全descendant終了
- [ ] ST-16 Ollama tool path脱出拒否
## 11.5 監査証跡
Security testでは「例外になった」だけでなく、OS/Brokerで実際に対象資源へ副作用が発生していない証跡を残す。
### Gate G6
ST-01〜11、16全PASS。Security不具合を残したまま進行禁止。
---
# 12. Phase 7 — Resource Transaction / Recovery
## 12.1 対応仕様
- Specifications 12〜13章、17章
- SEC-INV-10〜11
- REC-02、03、06、07
- ST-17、18のうちACL側
## 12.2 実装対象
- Recovery Journal
- CLEAN / PREPARING / APPLIED / RUNNING / CLEANING / RECOVERY_REQUIRED
- ACL適用前journal flush
- ACL journalは承認root単位とし、既存・新規descendantの継承とroot復元を検証
- Task Resource ownership
- cleanup逆順処理
- 起動前Recovery
- File Transaction
- memory snapshot / temp backup
- patch guard
- atomic replace
- rollback後hash検証
## 12.3 ACID対応
| 性質 | 実装上の確認 |
| --- | --- |
| Atomicity | ACL/File変更途中失敗時にrollbackされる |
| Consistency | Policyを満たさない状態でprocessを開始しない |
| Isolation | Task ID違いのResourceを誤cleanupしない |
| Durability | cleanupに必要なJournalがcrash後も残る |
## 12.4 強制Crash Test
最低限次の地点でProcessを意図的に終了させ、次回起動時にRecoveryを確認する。
- [ ] journal作成後、ACL前
- [ ] ACL適用直後
- [ ] sandbox process起動後
- [ ] File temp作成後
- [ ] replace直後、commit前
- [ ] cleanup途中
## 12.5 完了条件
- [ ] crash後に元ACLへ復旧
- [ ] temp resourceなし
- [ ] orphan processなし
- [ ] recovery完了前にMCP serveしない
- [ ] cleanup不能ならfatal
### Gate G7
全Recovery test PASS。残留Resourceゼロを証跡で確認する。
---
# 13. Phase 8 — Network Sandbox / WFP
## 13.1 対応仕様
- Specifications 11.4
- SEC-INV-06〜07
- ST-12〜14、ST-18
## 13.2 固定方針
```text
mode=deny
  -> localhostを含むoutbound全拒否

mode=allow
  -> default deny
  -> allow-list hostをTask開始時にDNS resolve
  -> IP snapshot + portだけallow
```
## 13.3 実装時にCodexが選択してよい範囲
- WFP layer
- sublayer
- filter condition
- transaction API sequence
ただし仕様を変更する選択は不可。
## 13.4 必須テスト
- [ ] denyで127.0.0.1拒否
- [ ] denyで外部host拒否
- [ ] allowで許可host:port成功
- [ ] allowで未許可port拒否
- [ ] allowで未許可host拒否
- [ ] DNS失敗時deny
- [ ] Task終了時WFP filter削除
- [ ] WFP適用直後crash→次回Recovery
## 13.5 Codex必須報告
WFP API選択理由を短く報告し、Windows SDK/APIの根拠と、どのSecurity Testで保証するかを記録する。
### Gate G8
Network Security Test全PASS、filter残留なし。
---
# 14. Phase 9 — Vision / Streamable HTTP
## 14.1 対応仕様
- OLL-09
- MCP-TR-02〜04
- AT-02、03、06
- ST-20
## 14.2 Vision
- `images` optional
- PNG/JPEG/WebP
- Base64 validation
- size/count上限
- Vision非対応modelはlocalized error
## 14.3 Streamable HTTP
- loopbackのみ
- `127.0.0.1` / `::1`
- non-loopback bindはfatal validation
- v1はTLSなし
- v1はHTTP認証なし
- 外部公開不可
- Legacy HTTP+SSEなし
- GET SSE listenerなし
## 14.4 必須テスト
- [ ] text-only requestは画像なしで従来どおり動作
- [ ] Vision対応modelで画像成功
- [ ] Vision非対応modelでlocalized error
- [ ] invalid Base64拒否
- [ ] loopback Streamable HTTP成功
- [ ] `0.0.0.0`等のbind拒否
- [ ] Legacy SSE endpointなし
- [ ] HTTP GET SSE開始なし
### Gate G9
Vision optional性とHTTP非公開性を確認。
---
# 15. Phase 10 — Audit / Security Hardening
## 15.1 対応仕様
- Specifications 16章、18〜20章
- NFR-01〜09
## 15.2 実装対象
- Application Log
- LLM Log
- Audit JSONL
- user-only log ACL
- error code / localized message分離
- audit event completeness
- testでstdio stdout purity保証
## 15.3 Audit最低Event
- `task.start`
- `task.end`
- `tool.call`
- `process.start`
- `process.exit`
- `file.write`
- `file.delete`
- `policy.deny`
- `network.rule.apply`
- `network.rule.remove`
- `recovery.start`
- `recovery.end`
## 15.4 Security Matrix全件再実行
ST-01〜ST-20をクリーン環境から再実行する。
各テストは以下を記録する。
| 項目 | 内容 |
| --- | --- |
| Test ID | ST-* |
| Setup | ACL/Config/fixture |
| Action | 実行内容 |
| Expected | 仕様上の期待 |
| Actual | 実測 |
| Result | PASS/FAIL |
| Evidence | log/audit/file/process state |
### Gate G10
ST-01〜20全PASS。skip 0。Security関連TODO 0。
---
# 16. Phase 11 — Acceptance / Release Audit
## 16.1 目的
Codexの自己申告ではなく、仕様書のAcceptance IDと実成果を1対1で監査する。
## 16.2 Acceptance Test
AT-01〜AT-20をすべて再実行する。

## 16.2.1 Release Bundle
- `dotnet publish -c Release -r win-x64 --self-contained true` を実行する。
- `agent-mcp.exe`、runtime/dependency、`agent.yaml`、en/ja locale、User Prompt、`skills/`、READMEを含むversion付きZIP、manifest、SHA-256を生成する。
- ソースツリー外の空directoryへ展開し、Bundle内の資源だけで `agent-mcp check`、stdio initialize、loopback HTTP起動を実行する。

## 16.2.2 Operational E2E Test
- E2E-01: Release Bundle、local Ollama、実測approval、stdio MCP Clientでfixtureのread/edit/process/build/test、日本語応答、Audit追跡、cleanupまで完走する。
- E2E-02: 同等の作業をloopback Streamable HTTPで完走し、Legacy SSE、GET SSE、non-loopback bindが存在しないことを確認する。
- Cloud model試験は任意互換試験とし、Release Gateへ含めない。
## 16.3 Requirement Traceability監査
最低限次のマトリクスを完成させる。
| Requirement | Implementation | Test | Result | Evidence |
| --- | --- | --- | --- | --- |
| MCP-TR-* | `<file/class>` | `<test>` | PASS/FAIL | `<log>` |
| OLL-* | ... | ... | ... | ... |
| AGT-* | ... | ... | ... | ... |
| PLN-* | ... | ... | ... | ... |
| SES-* | ... | ... | ... | ... |
| FS-* | ... | ... | ... | ... |
| PRC-* | ... | ... | ... | ... |
| I18N-* | ... | ... | ... | ... |
| REC-* | ... | ... | ... | ... |
| SEC-INV-* | ... | ... | ... | ... |
| NFR-* | ... | ... | ... | ... |
## 16.4 最終静的監査
- [ ] public MCP Toolが2個だけ
- [ ] Legacy SSEなし
- [ ] non-loopback HTTPなし
- [ ] Fixed Prompt変更I/Fなし
- [ ] MCP/LLMによるPolicy変更I/Fなし
- [ ] Internal Toolが5群から増えていない
- [ ] AppContainer profileをTaskごとに作成していない
- [ ] WFPが汎用Firewall engine化していない
- [ ] Database/ORMなし
- [ ] Workflow/Graph frameworkなし
- [ ] 未承認NuGet追加なし
- [ ] ambiguous巨大moduleなし
- [ ] test skipなし
- [ ] security TODO/FIXMEなし
- [ ] cleanup journal残留なし
## 16.5 文書監査
- [ ] 実装語彙がSpecifications/Designと一致
- [ ] 実装で追加された概念がDesignへ未記載ではない
- [ ] 実装制約が現在のコードと一致
- [ ] Configuration key索引と実際のkeyが一致
- [ ] Internal Tool Schemaと実装が一致
- [ ] MCP Schemaと実装が一致
### Gate G11 — Release Candidate
次をすべて満たした場合のみRelease Candidateとする。
1. Build PASS
2. Unit Test PASS
3. Integration Test PASS
4. ST-01〜20 PASS
5. AT-01〜20 PASS
6. Requirement traceability完成
7. 未承認依存0
8. Security関連未完了0
9. 仕様・設計逸脱0、または承認済み文書更新済み
10. Recovery後のclean state確認
11. publish済みwin-x64 self-contained Release Bundleが単独で起動可能
12. E2E-01 / E2E-02がlocal OllamaでPASS
13. READMEだけでfresh directoryから初回セットアップ可能
---
# 17. フェーズ横断テスト分類
| 種別 | 目的 | 実行タイミング |
| --- | --- | --- |
| Unit | 純粋ロジック検証 | 毎Phase |
| Integration | Ollama/MCP/Windows API境界 | 対象Phase以降 |
| Security | deny、escape、hash、network | Phase 6以降 |
| Recovery | crash後cleanup | Phase 7以降 |
| Acceptance | 仕様の外部性質 | Phase 11 |
| Regression | 既存Gate破壊の検出 | 全Phase |
各Phase完了時は、そのPhaseの新規テストだけでなく**それ以前の全自動テスト**を再実行する。
---
# 18. Codexが作業を停止して設計レビューへ戻す条件
Codexは次の場合、独自判断で迂回実装せず作業を停止し報告する。
| 条件 | 禁止される対応 |
| --- | --- |
| Windows API制約でSecurity Invariantを満たせない | Policyを暗黙緩和する |
| MCP SDKが想定transportを提供しない | 独自transportを作る |
| CsWin32でAPIを扱いにくい | 無断で大規模native layerを導入する |
| WFP host/port実装が複雑 | unrestricted networkへ変更する |
| Recoveryが難しい | cleanupをbest-effortに変更する |
| Ollama option/API差異 | optionを silently ignoreする |
| dependency不足 | 無断でNuGetを追加する |
| Design語彙で表現不能 | 独自概念を勝手に作る |
報告には次を含める。
1. 該当Requirement
2. 該当Design
3. 技術的制約
4. 再現手順
5. 仕様を変更しない代替案
6. 仕様変更が必要な場合はその影響範囲
---
# 19. Codex向け変更管理ルール
## 19.1 1フェーズ1主目的
無関係なrefactorを同じ差分へ混ぜない。
## 19.2 Dependency追加
新しいNuGet packageを追加する前に作業を止め、以下を報告する。
- package名/version
- 必要理由
- .NET標準/CsWin32/MCP SDKで代替不能な理由
- runtime dependencyかbuild-time dependencyか
- security/maintenance影響
## 19.3 文書変更
以下を変更する場合はコードより先に `Specifications.md` / `Design.md` の変更案を提示する。
- MCP Schema
- SandboxPolicy Schema
- Task state
- Security Invariant
- public CLI surface
- Internal Toolの追加・削除
- HTTP公開範囲
- Prompt優先順位
---
# 20. 監査用進捗台帳
Codex作業後、人間はこの表を更新する。
| Phase | Gate | Codex報告 | Build | Tests | Security | Evidence確認 | 人間監査 | 備考 |
| ---: | --- | --- | --- | --- | --- | --- | --- | --- |
| 0 | G0 | ☐ | ☐ | ☐ | N/A | ☐ | ☐ | |
| 1 | G1 | ☐ | ☐ | ☐ | N/A | ☐ | ☐ | |
| 2 | G2 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 3 | G3 | ☐ | ☐ | ☐ | N/A | ☐ | ☐ | |
| 4 | G4 | ☐ | ☐ | ☐ | N/A | ☐ | ☐ | |
| 5 | G5 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 6 | G6 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 7 | G7 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 8 | G8 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 9 | G9 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 10 | G10 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
| 11 | G11 | ☐ | ☐ | ☐ | ☐ | ☐ | ☐ | |
---
# 21. Phase監査記録テンプレート
各Phaseについて以下をコピーして使用する。
```markdown
## Audit Record — Phase X

- Codex実施日時:
- 対象commit:
- 前提commit:
- Reviewer:

### 1. Scope
- 計画内の変更: PASS / FAIL
- 計画外変更: None / ...

### 2. Build
- command:
- result:

### 3. Tests
- unit: <passed>/<failed>/<skipped>
- integration: <passed>/<failed>/<skipped>
- security: <passed>/<failed>/<skipped>

### 4. Requirement Trace
- Requirement IDs:
- Implementation files:
- Test IDs:

### 5. Diff Review
- 不要な抽象化: None / ...
- 新規dependency: None / ...
- 新規public surface: None / ...
- TODO/FIXME: None / ...

### 6. Security Review
- Policy bypass path: None / ...
- negative test evidence:
- cleanup evidence:

### 7. Evidence
- build log:
- test log:
- audit log:
- other:

### 8. Result
- Gate: PASS / FAIL
- Rework required:
- Notes:
```
---
# 22. 最終監査でCodexに提出させる一覧
- [ ] 最終変更ファイル一覧
- [ ] 最終Project dependency graph
- [ ] 最終NuGet package一覧
- [ ] MCP Tool一覧
- [ ] Internal Tool一覧
- [ ] Configuration key一覧
- [ ] Locale key一覧
- [ ] Test一覧
- [ ] ST-01〜20結果表
- [ ] AT-01〜20結果表
- [ ] Requirement Traceability Matrix
- [ ] TODO/FIXME/Skip一覧
- [ ] Recovery crash test結果
- [ ] Audit Log sample
- [ ] Known limitations
- [ ] Specifications/Designからの逸脱一覧（原則0件）
---
# 23. Definition of Done
本アプリケーションのv1実装完了は、単に機能が動作することではなく、次をすべて満たすこととする。
- 仕様の外部性質を満たす。
- Designの責務境界を維持する。
- MCP public surfaceが2 Toolに限定される。
- OllamaだけをLLM backendとして使用する。
- SandboxPolicyをLLM/MCPから緩和できない。
- Filesystem / Process / Networkのnegative testが成立する。
- descendantが権限を拡大できない。
- crash後にTask Resourceを残さない。
- Token Plannerが決定的に検証できる。
- en/jaおよび追加Localeの仕組みが成立する。
- Audit Logから重要な副作用を追跡できる。
- 全Acceptance TestがPASSする。
- 全Security TestがPASSする。
- skipped test、Security TODO、未承認dependencyが0である。
- Codexの主張ではなく、再実行可能な証跡によって上記を確認できる。
- Release build、Unit、Integration、ST-01〜20、AT-01〜20、Operational E2EがすべてPASSする。
- Release Bundle単独でstdio/Streamable HTTPを実利用できる。
- orphan process、ACL、WFP filter、temporary resource、journalの残留が0である。
- READMEだけで初回セットアップからTask実行、Audit確認、安全な終了まで再現できる。

# 24. MCP 2026-07-28 Migration Gate

- 公式C# SDK `2.0.0`とTasks Extension `2.0.0`をCentral Package Managementで固定する。
- stateless `server/discover`、必須request `_meta`、header mismatch/unsupported version、GET/DELETE 405、Session ID非発行を検証する。
- modern経路とlegacy initialize fallbackを別々に検証し、Inspector固有の互換middlewareを追加しない。
- Tasksの対応/非対応client、create/get/cancel、TTL、atomic persistence、restart failure recovery、Agent Task相関を検証する。
- `@modelcontextprotocol/conformance@0.2.0-alpha.11`を取得処理とoffline実行に分離し、version/integrity/scenario一覧を`artifacts/evidence/mcp-2026-07-28/`へ保存する。
- conformanceのapplication failure、診断fixture不足、runner自身のalpha schema不整合、upstream skipを別集計する。expected-failure baselineでapplication failureを隠さない。
- production hostに不要な診断Tool/Resource/Promptはtest-only hostへ隔離し、Release Bundleへ含めない。
- Gate完了にはRelease/全test/Operational E2Eに加え、applicable conformance checkのapplication failure 0を要求する。