---
name: workflow-navigation-contract
scope:
  - '*'
products:
  - '*'
id: ka-hard-rule-工作流导航契约规则
type: governance_rule
asset_kind: governance_rule
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-workflow-navigation-contract
asset_role: required
consumed_by:
  - mc-workflow-navigation-contract
  - consumable_asset_registry
  - knowledge_injection
routes: ['operation', 'artifact_generation']
primary_triggers:
  - 工作流导航契约规则
secondary_triggers:
  - 下一步
  - 继续
  - 现在能写代码吗
  - 导航
  - navigation
negative_triggers: []
priority: P0
specificity: 5
consumes:
  - mc-workflow-navigation-contract
hard_blocks:
  - stale_task_bypass
  - disallowed_action_execution
fallback: manual_required
required_evidence:
  - project_stage
  - task_stage
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["*"]
---

## 核心原则

执行任何开发动作前，必须先查询工作流导航状态。不得绕过导航机制凭经验操作。

查询方式：`soloforge next`（CLI）或 `sf_navigation`（MCP 工具）。

导航必须把用户确认项分为三类：

1. `must_confirm`：影响业务口径、架构决策、权限模型、API/数据库语义、陈旧任务处理等不可由 AI 代决的事项。只有这类确认可以阻塞推进。
2. `should_confirm`：确认后准确性更高，但不确认也允许继续只读分析、初始化、模版同步和低风险准备。
3. `auto_resolvable`：可通过命令、复验或修复动作解决的事项，不应要求用户拍板。

AI 不得只说“需要确认”。必须说明哪些是必须确认、哪些只是建议确认、哪些可以自动处理，并说明不确认的影响和下一步命令。

从 0 开发的新项目没有既有项目事实可确认。此时只能确认目标、边界、技术选择和默认口径；不得把自动推断当成已有系统事实，也不得因为缺少既有事实阻塞初始化和只读规划。

## 禁止动作规则

以下 7 条规则在工作流导航中强制执行：

1. **设计审计失败 → 禁止写业务代码**
   - 条件：design_artifact_pack.status 不是 implementation_ready
   - 阻断：sf_execute
   - 必须先通过设计审计复验

2. **配置未确认 → 区分自动修复与业务确认**
   - 条件：项目阶段为 configuration_pending
   - 阻断：除 sf_init、config_confirm 外的所有动作
   - version 数字/字符串、scope 字符串/数组、config.evidence.json 缺失/过期/不匹配属于自动修复项，必须提示 soloforge config repair
   - 产品类型、技术栈选择、仓库边界、业务范围等语义口径才进入 config confirm 或用户确认

3. **决策未确认 → 禁止定稿架构/详细设计/代码**
   - 条件：架构决策研讨中存在未确认域
   - 阻断：sf_execute、sf_expand
   - 必须先完成决策研讨并获取用户确认

4. **无开发切片计划 → 禁止大范围编码**
   - 条件：expansion 存在但 planning 不存在
   - 阻断：sf_execute（大范围）
   - 必须先生成切片规划工作包

5. **修复重验指令未清零 → 禁止交付**
   - 条件：repair_reverify_directive.blocked = true
   - 阻断：sf_deliver
   - 必须先完成修复和复验

6. **测试失败 → 禁止交付**
   - 条件：verification_result.status = failed
   - 阻断：sf_deliver
   - 必须先修复测试

7. **本地验收缺失 → 禁止交付结论**
   - 条件：delivery_ready 但无 local_acceptance_evidence
   - 阻断：sf_deliver
   - 必须先完成本地验收

## 陈旧任务处理协议

当检测到陈旧任务时（如 current-task.json 指向旧任务）：

- **不得绕过 SoloForge 状态直接操作**
- **不得说"无需 SoloForge 状态"然后自由发挥**
- **不得把取消、归档或 Bash 写入当作恢复路径**
- 必须从三个选项中选择：恢复旧任务 / 归档旧任务 / 开始新任务
- 旧任务文件不得静默删除，只处理 current-task 指针
- 选择必须留有审计痕迹

## 阻断恢复协议

当 SoloForge 的 Edit/Write/Bash hook 或 MCP 工具返回阻断时：

- 不得建议“取消任务后直接写代码”。
- 不得建议“先用 Bash 直接修改业务代码”。
- 不得建议手动删除或清理 `.soloforge/state`。
- 不得把“先实现后补验证”作为恢复路径。
- 必须按工具返回的 `recovery_command`、`soloforge next`、`sf_expand`、`sf_verify` 或经用户确认的 `sf_status action=archive_stale confirm=true` 恢复。
- 只有 `soloforge next` 或 `sf_status` 明确判定 current-task 陈旧时才允许归档；归档后仍必须重新 `sf_classify -> sf_expand` 建立受控任务，不能直接写代码。

## Override 协议

用户可以显式 override 导航建议，但必须包含：
- override_reason：覆盖原因
- user_confirmation_ref：用户确认引用
- risk_acknowledged：已确认风险

无痕 override 不允许。

## JSON 输出契约

`soloforge next --json` 输出纯 JSON 到 stdout，无日志污染。
字段包含：project_stage、task_stage、confidence、stage_evidence、blocking_reasons、confirmation_decisions、recommended_commands、recommended_prompt、disallowed_next_actions、work_package。

`confirmation_decisions` 必须包含：

- `must_confirm`
- `should_confirm`
- `auto_resolvable`
- `blocked_reason`
- `recommended_action`
