chore: rebase main and reconcile docs-first runtime changes

.github/workflows/ci-gate.yml

@@ -122,3 +122,13 @@ jobs:
 
       - name: Check lockfile update policy
         run: ./scripts/ci/check_lockfile_policy.sh
+
+  design-doc-drift:
+    name: design-doc-drift
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check design documentation drift
+        run: ./scripts/ci/check_design_doc_drift.sh

AGENTS.md

@@ -3,3 +3,23 @@
 
 - When writing code, add necessary comments to clarify non-obvious logic or intent.
 - When creating a commit, include a detailed commit message (summary + body with key changes and rationale).
+
+## Documentation-First Governance (Mandatory)
+
+- Agent-driven development MUST follow documents under `docs/guides/` first, especially:
+  - `docs/guides/Development_Constraints.md`
+  - `docs/guides/Documentation_First_Development_SOP.md`
+- Code implementation MUST align with `docs/design/` as the latest full design source of truth.
+- If design and implementation diverge, update design docs first, then execute gap analysis before coding.
+- Every design doc that governs implementation MUST explicitly contain:
+  - overall architecture
+  - core workflow
+  - data structures
+  - key interfaces
+  - exception/error handling
+- For any bug fix, feature, or refactor, follow the SOP sequence:
+  1. update design docs
+  2. generate design-code gap analysis
+  3. derive TODO list from the analysis
+  4. execute fixes via OpenSpec workflow task-by-task
+  5. update TODO/evidence and archive analysis artifacts

CLAUDE.md

@@ -5,6 +5,7 @@
 
 - **Project Context**: `openspec/project.md` - 技术栈、架构、约定
 - **AI Agent Guidelines**: `CONTRIBUTING_AI.md` - AI Agent 协作规则
+- **Docs-First SOP**: `docs/guides/Documentation_First_Development_SOP.md` - 文档先行开发流程
 - **OpenSpec Workflow**: `openspec/AGENTS.md` - 变更提案流程
 - **Design Docs**: `docs/design/` - 架构设计文档
 
@@ -24,8 +25,14 @@ Milestone Loop → Observe → Plan → Validate → Execute → Verify → Reme
 Tool Loop      → Gather → Act → Check → Update (in WorkUnit)
 ```
 
+## Model Usage Policy
+
+- **代码搜索、文件查找、内容检索**：必须且只能使用 Sonnet 或 Haiku 模型（`claude-sonnet-4-6` / `claude-haiku-4-5-20251001`）
+- **思考分析、代码生成**：必须且只能使用 Opus 模型（`claude-opus-4-6`）
+
 ## Before You Code
 
 1. Read `openspec/project.md` to understand the project
 2. Read `CONTRIBUTING_AI.md` to understand collaboration rules
-3. For major changes, use `/openspec:proposal` first
+3. Update `docs/design/` first and satisfy `docs/design/Design_Doc_Minimum_Standard.md`
+4. For implementation changes, use `/openspec:proposal` first

CONTRIBUTING_AI.md

@@ -2,7 +2,7 @@
 
 本文档定义 AI Agent（Claude、GPT、Gemini 等）在本项目中协作的规则和约定。
 
-> 必读：在任何开发前，请先阅读并遵守 `docs/guides/Development_Constraints.md`（通用开发约束）以及本文件。若你的变更涉及沙箱执行、WORM 审计、Envelope/DonePredicate 强制，请同时遵循 `docs/guides/Engineering_Practice_Guide_Sandbox_and_WORM.md`。
+> 必读：在任何开发前，请先阅读并遵守 `docs/guides/Development_Constraints.md`、`docs/guides/Documentation_First_Development_SOP.md`、`docs/design/Design_Doc_Minimum_Standard.md` 以及本文件。若你的变更涉及沙箱执行、WORM 审计、Envelope/DonePredicate 强制，请同时遵循 `docs/guides/Engineering_Practice_Guide_Sandbox_and_WORM.md`。
 
 ## 核心原则
 
@@ -37,19 +37,19 @@ Agent 不应依赖自己的"记忆"来保持状态：
 
 ## 工作流程
 
-### 使用 OpenSpec 进行重大变更
+### 文档先行 + OpenSpec 执行（强制）
 
-所有以下类型的变更必须通过 OpenSpec：
+所有涉及代码行为变化的变更，必须先走“文档先行 SOP”，再通过 OpenSpec 执行：
 
-| 变更类型 | 需要 OpenSpec? | 说明 |
-|---------|---------------|------|
-| 新增核心接口 | 是 | 七个不可变接口的任何修改 |
-| 新增组件 | 是 | 添加新的核心组件 |
-| 架构调整 | 是 | 三层循环的任何修改 |
-| 新增工具 | 视情况 | 高风险工具需要 |
-| Bug 修复 | 否 | 直接修复并提交 |
-| 重构（不改接口） | 否 | 确保测试通过 |
-| 文档更新 | 否 | 直接提交 |
+| 变更类型 | 文档先行 SOP | OpenSpec 执行 | 说明 |
+|---------|--------------|---------------|------|
+| 新增核心接口 | 是 | 是 | 先补设计，再提案与实现 |
+| 新增组件 | 是 | 是 | 先定义契约与边界，再实现 |
+| 架构调整 | 是 | 是 | 先更新架构文档与影响分析 |
+| 新增工具 | 是 | 是 | 含风险等级、审批策略与错误语义 |
+| Bug 修复 | 是 | 是 | 先定位是否文档约束缺失，再修复 |
+| 重构（不改接口） | 是 | 是 | 先补齐设计约束与迁移策略 |
+| 纯文档更新（无代码） | 是 | 否（可选） | 仅文档修订可不走实现任务 |
 
 #### OpenSpec 工作流
 
@@ -64,26 +64,28 @@ flowchart LR
     F --> G[归档 Proposal]
 ```
 
-1. **创建 Proposal**: 运行 `/openspec:proposal`
-2. **等待评审**: 人类或其他 Agent 评审
-3. **实现代码**: 评审通过后运行 `/openspec:apply`
-4. **归档**: 部署后运行 `/openspec:archive`
+1. **更新设计文档**：先更新 `docs/design/**`，满足最小完备标准。
+2. **生成 Gap 分析**：产出设计-代码差异分析文档。
+3. **生成 TODO 清单**：从 Gap 映射到可执行 TODO。
+4. **创建 Proposal**：运行 `/openspec:proposal`。
+5. **等待评审**：人类或其他 Agent 评审。
+6. **实现代码**：评审通过后运行 `/openspec:apply`，按 TODO 逐项落地。
+7. **回写与归档**：更新 TODO/证据，部署后运行 `/openspec:archive`。
 
 ### 日常开发流程
 
 ```mermaid
 flowchart TB
-    A[接收任务] --> B{需要 OpenSpec?}
-    B -->|是| C[创建 Proposal]
-    B -->|否| D[理解现有代码]
-    C --> E[等待评审]
-    E --> D
-    D --> F[编写代码]
+    A[接收任务] --> B[更新设计文档]
+    B --> C[生成 Gap 分析与 TODO]
+    C --> D[创建 OpenSpec Proposal]
+    D --> E[等待评审]
+    E --> F[编写代码]
     F --> G[运行测试]
     G --> H{测试通过?}
     H -->|否| F
     H -->|是| I[提交代码]
-    I --> J[更新文档]
+    I --> J[回写 TODO 与证据并归档]
 ```
 
 ---

dare_framework/agent/builder.py

@@ -60,9 +60,11 @@
     IPlannerManager,
     IRemediator,
     IRemediatorManager,
+    IStepExecutor,
     IValidator,
     IValidatorManager,
 )
+from dare_framework.security import ISecurityBoundary
 from dare_framework.skill import Skill, ISkillLoader, ISkillStore, SkillStoreBuilder
 from dare_framework.skill._internal.action_handler import SkillsActionHandler
 from dare_framework.skill._internal.filesystem_skill_loader import FileSystemSkillLoader
@@ -600,6 +602,9 @@ def __init__(self, name: str) -> None:
 
         self._event_log: IEventLog | None = None
         self._execution_control: IExecutionControl | None = None
+        self._execution_mode: str = "model_driven"
+        self._step_executor: IStepExecutor | None = None
+        self._security_boundary: ISecurityBoundary | None = None
         self._hooks: list[IHook] = []
         self._telemetry: ITelemetryProvider | None = None
         self._verbose: bool = False
@@ -624,6 +629,21 @@ def with_execution_control(self, execution_control: IExecutionControl) -> DareAg
         self._execution_control = execution_control
         return self
 
+    def with_execution_mode(self, execution_mode: str) -> DareAgentBuilder:
+        normalized = execution_mode.strip().lower()
+        if normalized not in {"model_driven", "step_driven"}:
+            raise ValueError("execution_mode must be 'model_driven' or 'step_driven'")
+        self._execution_mode = normalized
+        return self
+
+    def with_step_executor(self, step_executor: IStepExecutor) -> DareAgentBuilder:
+        self._step_executor = step_executor
+        return self
+
+    def with_security_boundary(self, security_boundary: ISecurityBoundary) -> DareAgentBuilder:
+        self._security_boundary = security_boundary
+        return self
+
     def add_hooks(self, *hooks: IHook) -> DareAgentBuilder:
         self._hooks.extend(hooks)
         return self
@@ -733,6 +753,9 @@ def _build_impl(
             event_log=self._event_log,
             hooks=hooks,
             telemetry=telemetry,
+            step_executor=self._step_executor,
+            execution_mode=self._execution_mode,
+            security_boundary=self._security_boundary,
             agent_channel=agent_channel,
             verbose=self._verbose,
             approval_manager=approval_manager,