diff options
Diffstat (limited to 'plans/ImplementationPlan.md')
| -rw-r--r-- | plans/ImplementationPlan.md | 757 |
1 files changed, 757 insertions, 0 deletions
diff --git a/plans/ImplementationPlan.md b/plans/ImplementationPlan.md new file mode 100644 index 0000000..c31f178 --- /dev/null +++ b/plans/ImplementationPlan.md @@ -0,0 +1,757 @@ +# 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 +## 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`競合を拒否 +- [ ] 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時に副作用なし +- [ ] 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 +- 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 +- 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.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確認 +--- +# 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の主張ではなく、再実行可能な証跡によって上記を確認できる。 |