---
id: ka-workflow-rules
kind: knowledge
title: 工作流硬规则契约
sync_policy: internal
status: active
extra:
  name: workflow-hard-rules
  category: governance_rule
  scope:
    - '*'
  verification_layer: L2
  owner_mechanism: mc-workflow-contract
  hard_rules:
    - rule_id: wf-routing-gate
      rule_summary: 权威状态操作必须使用当前 MCP 工具
      user_instruction: 项目文件由宿主直接编辑；任务、完整验证、审查、豁免和升级状态只能通过对应的 SoloForge MCP 工具操作，不得手工改写 `.soloforge/`。
      mechanism_id: mc-workflow-contract
      enforcement_status: enforced
    - rule_id: wf-multi-stage-loop
      rule_summary: 每个产物按 skill、编辑、quick、full、推进闭环
      user_instruction: 一次处理一个产物：选择对应 skill，完成必要研讨，编辑真实文件，由 hook-check 自动给出即时反馈以修正明显问题，再执行 `sf_verify action="full"`；当前阶段证据齐全后才调用 `sf_task action="advance"`。
      mechanism_id: mc-workflow-contract
      enforcement_status: enforced
    - rule_id: wf-dispatch-by-route
      rule_summary: 任务阶段由 sf_task 管理且生成过程不写生命周期状态
      user_instruction: 当前阶段和 scope 以 `sf_task action="query"` 返回为准。Skill 和 hook 不得推进任务或伪造验证记录。
      mechanism_id: mc-task-context-lifecycle
      enforcement_status: enforced
    - rule_id: wf-verify-after-change
      rule_summary: 产物变化后必须重新执行完整验证
      user_instruction: 产物内容变化后旧证据会失效。使用 `sf_verify action="full" task_id="..." artifact="..."` 重新验证；hook 通过不能替代 full。
      mechanism_id: mc-verifier
      enforcement_status: enforced
    - rule_id: wf-learn-after-verify
      rule_summary: 验证失败必须修复同一产物并重新 full
      user_instruction: Full 失败后按结构化 findings 修复根因，再对同一产物重新 full。达到 retry 上限时停止机械重试并向用户说明根因和选择。
      mechanism_id: mc-verifier
      enforcement_status: enforced
    - rule_id: wf-no-auto-capability-change
      rule_summary: 高影响状态和能力变化必须显式确认
      user_instruction: Reset、cancel、升级 apply、豁免等高影响操作必须满足工具确认契约；脚手架只返回预览，模型不得未经路径、冲突和内容审查就写入。
      mechanism_id: mc-guard-evaluation
      enforcement_status: enforced
    - rule_id: wf-privacy-before-expand
      rule_summary: 敏感输入在读取和持久化前必须先检查
      user_instruction: 读取外部材料或持久化任务意图前先执行隐私与凭据检查；secret 和 credential 不得进入 prompt、日志或任务状态。
      mechanism_id: mc-privacy-boundary
      enforcement_status: enforced
    - rule_id: wf-command-contract
      rule_summary: 高风险命令必须通过命令契约和用户确认
      user_instruction: 命令执行遵守 `command_execution_contract`；破坏性、外部写入和不可逆命令必须等待用户确认。
      mechanism_id: mc-command-execution
      enforcement_status: enforced
    - rule_id: wf-tool-contract
      rule_summary: MCP 工具调用必须满足授权和副作用契约
      user_instruction: 调用 MCP 工具前遵守工具的授权、副作用和确认要求；只读结果不能冒充完成态。
      mechanism_id: mc-tool-invocation-contract
      enforcement_status: enforced
    - rule_id: wf-core-principles
      rule_summary: 实施前先还原目标、约束和验收
      user_instruction: 先确认真实目标、适用范围和验收证据；有方向性歧义或不可逆决策时询问用户，其余细节按最简单的正确方案推进。
      mechanism_id: mc-core-engineering-principles
      enforcement_status: enforced
    - rule_id: wf-evidence-grounding
      rule_summary: 关键事实和交付结论必须有真实证据
      user_instruction: 关键事实、验证结果和交付结论必须引用真实文件、命令结果或权威记录。计划、推测和 quick 结果不是完整验证证据。
      mechanism_id: mc-evidence-grounding
      enforcement_status: enforced
    - rule_id: wf-architecture-workshop-first
      rule_summary: 高影响设计先由 skill 引导用户确认关键决策
      user_instruction: 涉及架构、数据、安全、接口、部署或跨模块边界时，先用对应 skill 与用户收敛关键选择和取舍，再编辑正式产物；不得由任务服务替用户决定领域内容。
      mechanism_id: mc-architecture-decision-workshop
      enforcement_status: enforced
    - rule_id: wf-design-artifact-pack
      rule_summary: 设计产物必须按依赖和 cross-artifact 规则完整验证
      user_instruction: 需求、原型、架构、数据库、API 和切片计划按产物契约维护；上游变化后重新 full，不能用过期文档支撑编码或交付。
      mechanism_id: mc-design-artifact-pack
      enforcement_status: enforced
    - rule_id: wf-standard-asset-contract
      rule_summary: 正式资产必须满足结构和消费契约
      user_instruction: 模板、规则、清单、脚手架和适配器输出必须有真实消费者并通过对应验证，不能只注册不消费。
      mechanism_id: mc-standard-asset-contract
      enforcement_status: enforced
    - rule_id: wf-template-asset-visibility
      rule_summary: 内部治理资产和用户项目资产必须隔离
      user_instruction: internal-only 资产不得同步到用户项目；不同技术栈规则只在适用范围内消费。
      mechanism_id: mc-template-asset-visibility
      enforcement_status: enforced
    - rule_id: wf-navigation-contract
      rule_summary: 模糊推进和阻断恢复先查询任务与证据状态
      user_instruction: 用户说“继续”或询问能否推进时，先调用 `sf_task action="query"`。遇到阻断按返回的恢复建议修复，不手工改状态或绕过 full。
      mechanism_id: mc-workflow-navigation-contract
      enforcement_status: enforced
    - rule_id: wf-code-observability
      rule_summary: 关键业务路径必须可维护且可观测
      user_instruction: 关键写入、权限、支付、状态变化和外部调用保留必要中文注释与结构化日志；不得记录敏感信息或吞异常。
      mechanism_id: mc-code-maintainability-observability-contract
      enforcement_status: enforced
    - rule_id: wf-no-lazy-code
      rule_summary: 代码和文档不得保留占位或空实现
      user_instruction: 不得提交空函数、空 catch、TODO、未实现占位、空洞章节或伪造证据。确定性 validator 会在 full 时检查。
      mechanism_id: mc-code-quality-gate
      enforcement_status: enforced
---

# 工作流硬规则契约

该资产由 `workflow_rule_generator` 消费并写入项目 `CLAUDE.md`。规则条数以 frontmatter 中的 `hard_rules` 为准。