peterwangze/software-project-governance

软件项目治理

面向 AI 编码交付的信任层，用于基于证据的规划、评审、风险、质量与发布控制。

软件项目治理帮助 AI 编码代理保持交付可信，同时让你专注于产品与技术决策。它面向市场审核人员、AI 编码用户，以及需要一种可重复方式来阻止漂移、证据缺失、评审循环薄弱和过早发布声明的团队。

市场审核就绪

当你的 AI 编码设置需要以下内容时，请使用此工作流：

- 基于证据的交付：每个有意义的任务都可以携带关于改了什么、为什么改、如何验证以及仍有哪些风险的事实。
- 门禁与风险控制：阶段门禁、任务状态、风险、决策和发布就绪状态保持相互关联，而不是散落在零散的聊天记忆中。
- 评审者分离与降级模式诚实性：该工作流区分真正的独立评审与降级或依赖环境的执行，并且不会把每个代理都呈现为完全受支持。
- 面向新用户的 5 分钟入门：从 /governance 开始，初始化 .governance/，然后让代理恢复状态、检查门禁，并只呈现关键决策。

1.0.0 就绪边界
0.57.0 打包了 0.55.0 动态生命周期迁移预览与外部验证归档、0.55.1 Web 控制台 CLI/客户端入口补丁、0.55.2 被动 Web 摘要入口补丁、0.55.3 治理入口修正、0.56.0 zcode 插件市场适配器、FIX-151 Web 控制台真实数据仪表盘补丁（0.56.1），以及 AUDIT-121 架构退化审计归档（无功能性代码变更）。它不是 1.0.0 版本。0.57.0 是一个仅文档/治理的版本：它归档了全项目架构退化诊断（docs/requirements/architecture-degradation-audit-0.57.0.md，F1-F6 事实：20,294 行的 verify_workflow.py 上帝模块、缺失的现代工程基础设施、源/投影重复、命令面冗余、自演化残留，以及架构健康管理缺口），新增了技术债务台账（skills/software-project-governance/core/technical-debt-ledger.md，TD-001~006），清理了根目录残留（nul、_fix_030_reconstruct.py），并规划了后续重构路线图（0.58.0 ArchGuard 作为独立能力版本，0.59.0~0.64.0 对 verify_workflow.py 进行渐进式按域拆分）。0.57.0 不修改 verify_workflow.py 功能代码，不实现 ArchGuard，不拆分任何模块，也不引入 lint/类型基础设施。该版本保留了 0.55.0 的仅干运行 dynamic-lifecycle-migration --target  --dry-run 预览、迁移指南、python_game 章节流验证归档，以及 shitu 非游戏验证归档。0.55.1 新增了 web-console --status 和 web-console --start [--install]；0.55.2 新增了 web-console --summary-link，用于只读的任务、阶段和会话摘要；0.55.3 恢复了预期的产品入口，使手动 /governance 通过 web-console --governance-entry 启动或复用本地 Web 控制台，然后报告 URL 以供后续 Web UI 交互；0.56.0 新增了 zcode 原生插件面（.zcode-plugin/、顶层 package.json）以及一次性 project/zcode-local-load.py 工具，使插件可在本地 zcode 安装中运行；0.56.1 修复了 Web 控制台仪表盘，使其读取真实治理数据而非硬编码模拟值，新增了 web/server.py API 服务器和 web/vite.config.js 代理，使所有仪表盘按钮均可正常工作，并保持仪表盘为只读的本地伴随工具。classic-phase-gate 仍是活动/默认兼容预设，dynamic-flow-gate 仍为非活动/非默认且仅限主动选择，本版本不迁移任何项目。外部验证仍有意保持保守：两个干运行预览均达到 READY_FOR_REVIEW，但安装状态验证仍存在目标原生阻塞项，且非游戏预设泛化仍不完整，因为 shitu 预览流单元仍来自 python_game_10_chapters 示例。RISK-036、RISK-037 和 RISK-039 仍处于开放状态：无官方批准、无市场批准（zcode 适配器仅证明本地加载/运行时可用；它未提交至 zcode 官方市场，也未获其批准）、无两个真实项目外部验证完全 PASS、无 Codex Desktop 生命周期 PASS、无项目迁移、无 ArchGuard 实现、无 RISK-036 关闭、无 RISK-037 关闭、无 RISK-039 关闭，也无 1.0.0 生产就绪声明。0.62.0 更新（FIX-167，DEC-093）：0.56.0 逆向工程的 project/zcode-local-load.py 种子哈希工具已被移除——较新的 zcode 运行时附带市场链，插件现通过共享的 Claude/zcode 市场协议安装（/plugin marketplace add peterwangze/software-project-governance）。这是符合协议的可安装性，仍不是 zcode 官方策展或批准；RISK-036/RISK-037/RISK-039 仍处于开放状态。
主流 Agent 加载

0.47.0 明确了当前主流 AI 编码 Agent 的加载路径。这是加载就绪性，而非官方批准、市场批准、通用/完整运行时支持，或 Codex Desktop 市场管理 E2E PASS。请参阅 docs/requirements/mainstream-agent-loading-0.47.0.md 中的 0.47.0 范围说明，以及 docs/requirements/runtime-readiness-matrix-0.43.0.md 中的公开运行时事实。

Tier 1 加载指南：

| Agent | 加载或安装路径 | 首次验证 | 当前边界 |
| --- | --- | --- | --- |
| Claude Code | 将此仓库添加为 Claude 插件市场，然后安装 software-project-governance@spg。 | python adapters/claude/launch.py 和 python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters --runtime | Claude target-cwd 读取用例在本地证据中为 PASS/DEGRADED。这并非官方市场批准。 |
| Codex | 使用 .agents/plugins/marketplace.json、.codex-plugin/plugin.json、AGENTS.md 和 skills/software-project-governance/SKILL.md 作为 Codex 插件/项目指导包。 | python -m json.tool .agents/plugins/marketplace.json、python -m json.tool .codex-plugin/plugin.json、python adapters/codex/launch.py 和 python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent codex --timeout 180 | 截至 2026-06-11，Codex CLI 无头 target-cwd 读取 E2E 为 PASS/DEGRADED。这仍不是 Codex Desktop 市场管理生命周期 PASS。 |
| Gemini CLI | 使用精简的 GEMINI.md 项目上下文指针指向 skills/software-project-governance/SKILL.md；自定义命令、MCP 和扩展仍为独立的扩展点。 | python adapters/gemini/launch.py，然后 GEMINI_CLI_TRUST_WORKSPACE=true python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent gemini --timeout 180 | 截至 2026-06-11，在启用无头工作区信任时，Gemini CLI target-cwd 读取 E2E 为 PASS/DEGRADED。无 Gemini 插件市场声明。 |
| opencode | 使用 AGENTS.md 或配置的 opencode 指令指向 skills/software-project-governance/SKILL.md。 | python skills/software-project-governance/infra/verify_workflow.py opencode-provider-preflight 和 python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent opencode --timeout 90 | opencode target-cwd 运行时 E2E 在本地证据中为 PASS/DEGRADED；provider/model 预检仍可防范未来回归。 |
| Chrys | Chrys 会将 AGENTS.md 和 CLAUDE.md 作为原生上下文自动加载，并为 skills/software-project-governance/SKILL.md 提供原生 load_skill。 | python adapters/chrys/launch.py 和 python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters | Chrys 是第一个拥有完整原生配置文件的适配器：原生 ask_user、sub_agent、tool_calling 和 git_hooks。仅浏览器和 MCP 仍依赖宿主环境。 |
| DeepSeek Harness (dsh) | 标准插件安装（由 pnpm 支持；推荐使用 link: 本地检出——实时代码，见下方 dsh 章节）：dsh plugin --profile web add link:/path/to/software-project-governance；也支持 file:（快照）和 github:peterwangze/software-project-governance。重启配置文件以激活 bundle 层——随后插入的行会渲染打包的预设，治理技能和 /governance 命令投影仅在该预设的会话中加载（其他预设如 standard 不携带治理技能；此作用域限定是 FIX-310 的核心行为目标，其真机确认仍待完成）。协调者角色预设：bundle 自身插入的宿主行（lib/index.js ensurePreset()）在启动时将 agent-presets/governance/agent.cordis.yml.template 渲染到 ${DSH_HOME}/.agent-presets/governance/，因此 governance 预设会在安装 + 重启后出现在预设名册中〔隔离：2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，仅限 Windows〕——用户预设根目录是第一个用户信任根，因此设置页面将其显示为自定义预设（可删除 + 打开文件夹，标签不是「内置」）。渲染按包版本幂等，失败时仅警告。可选手动路径（仅预设安装、离线、较旧 dsh）：python adapters/dsh/launch.py --install（先加 --dry-run 预览）会渲染字节完全相同的组合。按项目激活：python adapters/dsh/launch.py --bootstrap-project  写入一个精简的 AGENTS.md。 | dsh --profile  --dump-config 显示 @peterwangze/software-project-governance-plugin bundle 层；python adapters/dsh/launch.py --install --dry-run；python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters | dsh 与 Chrys 的原生配置文件相匹配（原生 ask_user_question、subagent、tool_calling、git_hooks；/governance 加载命令 shim 技能）。仅浏览器自动化和 MCP 仍依赖宿主环境。dsh 插件安装是官方 bundle 机制，并非市场审批或通用运行时声明。link:/github: 安装在 dsh 0.1.2-rc.1 + pnpm 11.22.0 的隔离 DSH_HOME 中于 2026-09-05 重新验证。 |
| zcode | 将此仓库添加为插件市场并安装：/plugin marketplace add peterwangze/software-project-governance，然后 /plugin install software-project-governance@spg。zcode 复用 Claude 市场协议（.claude-plugin/marketplace.json + .zcode-plugin/plugin.json）。 | python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters | 符合协议的市场安装。并非 zcode 官方策展或批准。0.56.0 逆向工程的本地加载工具已在 0.62.0 中退役（DEC-093）。 |

第 2 层兼容性与研究行：

| Agent | 需关注的加载面 | 0.47.0 状态 |
| --- | --- | --- |
| Cursor | 项目/用户/团队规则以及 AGENTS.md 风格的项目指令 | 仅作兼容性参考；无适配器清单或运行时 PASS。 |
| GitHub Copilot coding agent | 仓库自定义指令以及 AGENTS.md 自定义指令 | 仅作兼容性参考；无适配器清单或运行时 PASS。 |
| Cline | Markdown 规则，例如 Cline 规则文件 | 仅作兼容性参考；无适配器清单或运行时 PASS。 |
| Windsurf/Cascade | 工作区规则与记忆 | 仅作兼容性参考；无适配器清单或运行时 PASS。 |
| Kiro | 工作区引导文件，例如 .kiro/steering/ | 仅作兼容性参考；无适配器清单或运行时 PASS。 |

Claude Code：

/plugin marketplace add peterwangze/software-project-governance
/plugin install software-project-governance@spg

其他 Claude 路径：

/plugin install https://github.com/peterwangze/software-project-governance.git
git clone https://github.com/peterwangze/software-project-governance.git
/plugin install /path/to/software-project-governance

DeepSeek Harness (dsh) 插件安装 —— dsh plugin 是一个轻量的 pnpm 转发器，因此 add 规格是 pnpm 包规格（与 dsh-novel-writing 插件风格相同）。前提条件：dsh ≥ 0.1.2-rc.1（预设随 bundle 激活的版本边界；在 ≤0.1.1-rc.2 上使用下方的可选 launch.py 路径）、pnpm，对于 github: 形式还需要 git + 网络；launch.py 路径及所有验证命令需要 Python 3（python；某些 Linux/macOS 发行版使用 python3）。

本地检出，实时链接（推荐贡献者使用 —— 代码编辑在 profile 重启后生效）
dsh plugin --profile web add link:/path/to/software-project-governance
本地快照替代方案（内容寻址；升级需要先 remove 再 add）
dsh plugin --profile web add file:/path/to/software-project-governance
从 GitHub 安装（需要 git + 网络）
dsh plugin --profile web add github:peterwangze/software-project-governance

升级 / 卸载
dsh plugin --profile web update @peterwangze/software-project-governance-plugin
dsh plugin --profile web remove @peterwangze/software-project-governance-plugin
安装后重启 dsh web profile —— bundle 层在 profile 启动时生效（启动时，而非 HMR）。插入的行随后会将打包的 preset 渲染到 ${DSH_HOME}/.agent-presets/governance/，因此 governance preset（「治理协调器」）会出现在 preset 名册中〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕，并且 governance skills + /governance 命令投影仅在该 preset 的会话中加载 —— 其他 preset（例如 standard）上的会话不携带任何 governance skills（此作用域限定是 FIX-310 的核心行为目标；其真机确认仍待完成 —— 见发布检查清单的验收面）。交付是一次纯插入：cordis.patch.yml 仅添加一行，且只命名此包，因此 dsh --profile web --dump-config 与未打补丁的组合相比仅相差该行 —— 每个 dsh / dsh-web-app 行都保留其配置和 disabled 状态（DEC-187 I-1/I-2/I-3，经 DEC-188 ② 澄清；不修补任何 host 行，无 !!js 自定位，无 trust: system 根）。该行将 agent-presets/governance/agent.cordis.yml.template 渲染到 ${DSH_HOME}/.agent-presets/governance/，即用户 preset 根目录：因此设置页面会显示一个自定义 preset，并提供删除和打开文件夹操作，而组合中的 customSkillDirs 是指向该包的绝对路径，因此任何复制重新锚定都无法清空 skill 目录。移除：dsh plugin remove 撤回 bundle 行；删除用户根 preset 目录以移除最后渲染的副本（后续 dsh 启动会重新渲染它 —— 见下方说明）。

可选的手动 preset 侧路径（adapters/dsh/launch.py）—— 无需 bundle 行即可获得相同的渲染结果（仅 preset 安装、离线检出或脚本化安装）：

python adapters/dsh/launch.py --install --dry-run   # preview: resolved DSH_HOME + planned writes, zero side effects
python adapters/dsh/launch.py --install             # renders only ${DSH_HOME}/.agent-presets/governance/ (4 files: composition + preset.yml + 2 markers)

自 0.81.0 起，这些写入路径会拒绝真实 home（行为 B-2，docs/release/feature-flags-0.81.0.md 第 2 节）：除非将 DSH_HOME 显式设置为真实 home 树之外的目录，否则 --install / --sync / --uninstall 会以 [REFUSED] 退出 2（~/.dsh（未设置或为空均视为真实 home），因此有意的手动安装必须将 DSH_HOME 重定向到临时目录；--dry-run 仍为只读预览，依然允许。 〔static: 0.81.0 write-side guard, adapters/dsh/launch.py write_side_refusal + release-gate tests; refusal path not re-executed in this doc edit〕

安全验证边界（不要针对真实 ~/.dsh 进行“验证”）：使用 --dry-run 预览，然后针对重定向的 home 运行安装/升级检查 ——

DSH_HOME=$(mktemp -d) python adapters/dsh/launch.py --install        # isolated preset install
DSH_HOME=$(mktemp -d) dsh plugin --profile web add link:/path/to/software-project-governance
两种形式均以此方式重新验证（临时目录 DSH_HOME，对真实主目录零写入），验证环境为 dsh 0.1.2-rc.1 + pnpm 11.22.0，2026-09-05 —— 所有验证均在 Windows 上运行；非 Windows 环境未经验证〔isolation: link:/file: 2026-09-05, Windows-only〕〔static: github: form —— 打包语义基于推理，而非安装验证（见 RISK-049）〕。关于 github: 的说明：v0.79.0 和 v0.80.0 已打标签并推送（v0.80.0 剥离后指向 71f73eb；0.80.0 于 2026-09-12 发布 —— docs/release/release-checklist-0.80.0.md）且已推送到远程（0.81.0 的 M-7 完成了回推 —— 未推送标签/提交的数量在 docs/release/release-checklist-0.79.0.md 和 …-0.81.0.md §M-8 收尾义务中披露；M-7 推送承载 v0.79.0/v0.80.0 回推义务）。GitHub 的 master 现在提供 0.81.0（e376ddf），github: 安装形式可用于 v0.79.0/v0.80.0/v0.81.0；本地检出（link:/file:）仍是等效路径。

声明证据等级（RISK-049 披露，FEAT-014）：注册在 ADAPTER_CLAIM_REGISTRY 中的 dsh 声明（4 个声明类别 —— 会话投影 / 预设名册 / /governance 手势 / 安装形式边界）均标注了其验证等级 —— live-session = 在真实用户会话中验证（注明日期）；isolation = 在隔离/重定向环境中重新验证（注明日期）；static = 仅静态/检查推理，明确标注为未经执行验证。检查 28t（check-governance）对注册表映射进行机器检查；本 dsh 章节中注册表之外的陈述不在其覆盖范围内。

对称生命周期管理（安装 / 升级 / 降级 / 卸载 —— 各表面的官方命令）：

bundle layer (dsh plugin, the profile's pnpm registry)
dsh plugin --profile web add link:/path/to/software-project-governance          # install (+ restart)
dsh plugin --profile web update @peterwangze/software-project-governance-plugin # upgrade (+ restart; link: → git pull + restart; file: → remove + add)
dsh plugin --profile web remove @peterwangze/software-project-governance-plugin # uninstall (+ restart)
downgrade: remove, then add an older ref — add github:peterwangze/software-project-governance#v (pnpm git-ref semantics); link: → git checkout v + restart

governance preset (launch.py, the user preset root)
python adapters/dsh/launch.py --install          # install (add --dry-run to preview)
python adapters/dsh/launch.py --sync             # upgrade after git pull
python adapters/dsh/launch.py --uninstall        # uninstall — deletes exactly .agent-presets/governance/ (--dry-run to preview)
downgrade: git checkout v + --install (overwrites in place)
关键边界：dsh plugin remove 管理的是 profile 的 pnpm bundle 层——在 dsh ≥ 0.1.2-rc.1 上，它会移除整个包，包括 bundle 提供的 preset（这是对 dsh plugin add 安装的对称卸载）。它仍然从不触碰 ${DSH_HOME}/.agent-presets/：通过 launch.py --install 安装到那里的 preset 需通过 launch.py --uninstall（或手动删除目录）来卸载，而对一个从未作为 pnpm 依赖的 preset 执行 dsh plugin remove 会报告 ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS。

Codex 个人 marketplace 包：

python -m json.tool .agents/plugins/marketplace.json
python -m json.tool .codex-plugin/plugin.json
optional: if your Codex environment ships a plugin validator (e.g. a
plugin-creator skill's scripts/validate_plugin.py), run it against this
checkout — no validator is distributed with this repo.

Gemini 和 opencode 的轻量项目投影：

python adapters/gemini/launch.py
python adapters/opencode/launch.py

对于每个 agent，加载 skills/software-project-governance/SKILL.md 作为工作流入口，并让运行时记录存放在目标项目的 .governance/ 目录中。Adapter 和 marketplace 资产描述的是安装与加载路径；它们并不构成 marketplace 批准或通用运行时就绪的证据。

信任与数据边界

- 该工作流将项目治理状态写入你项目本地的 .governance/ 目录。
- 它使用本地文件、git hooks、验证脚本和 agent 可读的 skills 来保持交付事实可审查。
- 该仓库自身的 .governance/ 目录是 dogfood/示例运行时记录，不是要复制到你项目中的模板。
- Adapter 和 marketplace 资产描述的是安装与加载路径；它们并不构成 marketplace 批准或通用运行时就绪的证据。

5 分钟快速开始

第一条成功路径刻意保持很小：在学习完整治理模型之前，先获得一个本地信任信号。

1. 通过上述路径之一进行安装。
2. 在你的 AI 编码环境中打开项目根目录。
3. 运行 /governance；如果你的环境直接暴露状态，同样的第一个信号就是状态输出。
4. 查找 Delivery Trust Snapshot：目标、阶段、gate/setup 状态、风险、证据、下一步行动、preset 指导、验证信号，以及 no-overclaim 边界。
5. 如需进行无需外部凭据的本地仅演示检查，请运行：

python skills/software-project-governance/infra/verify_workflow.py first-run-demo --assert-snapshot

该快照是第一个信任信号：它证明工作流能够展示它知道什么、仍缺少什么，以及下一步有证据支撑的行动。它并不声称获得官方批准、marketplace 批准、通用/完整运行时支持，或 1.0.0 生产就绪状态。
外部首次会话测量与本地的演示分开跟踪。当前 0.43.0 的测量状态为 local_demo=PASS 和 external_pilot=NOT_MEASURED，详见首次会话测量证据。

可选的本地 Web 控制台

主要用户界面仍然是你的 AI 编码 CLI 或客户端：Claude Code、Codex、Gemini CLI、opencode 或其他代理宿主。web/ 控制台是一个可选的本地配套视图，适合那些希望在仍然通过 CLI/客户端驱动工作的同时获得更清晰状态界面的用户。

用它来进行本地配置、查看当前状态、扫描证据/风险，以及查看高级维护可见性。它不会取代 /governance，不会自动运行代理任务，也不构成 Codex Desktop 市场管理生命周期 PASS 的证据。

从相同的 CLI/客户端路径发现它：

python skills/software-project-governance/infra/verify_workflow.py web-console --status

手动 /governance 是用户进入 Web UI 的默认入口。它应当启动或复用本地控制台并打印 URL：

python skills/software-project-governance/infra/verify_workflow.py web-console --governance-entry

打印无副作用的页脚，代理应在任务、阶段或会话总结之后附加该页脚：

python skills/software-project-governance/infra/verify_workflow.py web-console --summary-link

从本仓库检出目录启动它：

python skills/software-project-governance/infra/verify_workflow.py web-console --start

在首次检出时，需显式包含依赖安装：

python skills/software-project-governance/infra/verify_workflow.py web-console --start --install

然后打开命令打印的本地 URL，通常为：

http://127.0.0.1:5173/

在 CLI/客户端会话中，手动 /governance 默认会启动或复用 Web 控制台，以便用户可以通过可读的本地仪表板继续交互。如果首次使用时缺少依赖，请运行 CLI 显示的显式安装路径。在任务、阶段或会话总结之后，代理应附加只读的 web-console --summary-link 结果：如果控制台已在运行，它会报告本地 URL；如果未运行，则报告手动启动命令。将执行权限保留在 CLI/客户端中；使用 Web 控制台查看状态、进行本地配置和后续交互。

首次运行预设指南：

| 预设 | 何时优先使用 | 它优化的目标 |
|--------|----------------|-----------------------|
| lite | 你想要最快的首次运行，或个人/MVP 项目 | 最少的问题和快速快照 |
| standard | 你正在进行团队交付或正常的产品项目 | 平衡的证据、门禁、风险和评审边界 |
| strict | 你处于受监管、高风险或对发布敏感的工作中 | 更强的证据和审批纪律 |
包是能力模块；profile 是治理强度预设。Profile 保持为 lite / standard / strict，当前 0.44.0 实现是注册表优先，没有物理拆分。

| 预设 | 默认启用的包 | 后续可添加的内容 |
|--------|-----------------------------|-------------------|
| lite | governance-core | 当 AI 输出质量需要可执行约束时，添加 quality-gates |
| standard | governance-core、quality-gates、release-governance、agent-team | 仅当可审计性以及适配器/清单纪律值得增加额外上下文时，添加 enterprise |
| strict | governance-core、quality-gates、release-governance、agent-team、enterprise | 保持所有包启用，并将任何降级的运行时视为发布风险 |

包成员资格不是完成证据。pack enabled 并不意味着存在任务证据、独立评审已通过、质量门已通过、发布门已通过、已获得官方批准、已获得市场批准，或已验证通用/完整运行时支持。

有关完整的中文安装细节和日常使用指导，请继续阅读下文。

中文详细说明

让 coding agent 帮你看护项目质量——你只负责思考，过程管理全自动。

一句话说明

你的 AI 编程助手（Claude / Codex / 其他）安装这个工作流后，会自动帮你做这些事：

- 每完成一个任务，自动记录证据（改了什么、为什么改、怎么验证的）
- 每推进一个阶段，自动检查 Gate（有没有遗漏、质量达标没）
- 遇到方向选择时，帮你列出选项和后果，你做判断
- 风险、决策、计划变更——全程留痕，可复盘

你不需要手动维护项目文档、不需要记住“上次做到哪了”、不需要提醒自己“该做 code review 了”。

自动化能力分级声明（plugin-contract.md L114）

本工作流对「自动/看护」的承诺按 plugin-contract.md 三级划分；禁止用笼统的「自动」一词同时指向 A 级与 C 级能力（plugin-contract.md L114 禁令——README 和对外文档必须显式说明当前各项能力处于哪一级）：

- A 级（Agent Protocol Automation）：行为协议自动化——agent 按协议纪律自动执行。本 README「一句话说明」「日常体验」中的自动承诺（「过程管理全自动」「自动记录证据」「自动检查 Gate」「工作流自动做的事」「记录更新、文件编辑、状态跟踪——全自动」等）与会话内 agent 动作（自动升级 bootstrap + 补全缺失结构、自动创建 .governance/ 治理文件、自动标记阶段、自动检查质量等）均属本级——agent 按协议纪律自动推进并记录，不是系统后台触发。
- B 级（CLI-Enforced Automation）：CLI/脚本强制——verify_workflow.py check-governance、status 与 commit hooks 在命令/commit 时点强制（= B 级）；「唯一命令」「5 分钟开始」「验证」中的 /governance 自动场景检测、自动诊断修复路由属本级（命令时点、事件驱动，非持续）。
- C 级（System Automation）：后台系统自动触发、不依赖 agent 记忆——未实现（roadmap）（plugin-contract.md L102：MCP/headless runner 仅有协议样例，无可用实现）。0.76.0 起经会话 bootstrap 的 check-governance --summary-only 自动运行的「会话级」健康摘要不是 C 级后台 daemon。

当前治理自动级别 = A 级 + B 级；C 级为 roadmap（未实现）。完整分级声明与对外宣示口径见 skills/software-project-governance/SKILL.md「自动化能力分级声明」；对外宣示不得把 C 级未实现说成已实现。README 中其余「自动」表述（如「安装后，工作流入口会在后续会话中自动可用」、适配器边界说明中的「headless 自动化」「browser 自动化」「dsh 自动注入」）为宿主/适配器加载机制或能力边界说明，与治理自动化分级无关。

可选本地 Web 控制台

当前主交互界面仍然是 CLI 或客户端：Claude Code、Codex、Gemini CLI、opencode 等。web/ 是可选的本地伴随控制台，用来把常用本地配置、状态、证据和风险以更清晰的浏览器界面展示出来。

推荐用法：

- 日常推进任务、确认决策、执行 /governance 仍在 CLI/客户端里完成。
- Web 控制台用于查看 Local Setup、Status、Evidence & Risks。
- Remote Validation、Release、Maintenance 属于 Advanced 高阶区，不放在首屏干扰普通用户。
- 这不是 Codex Desktop 内嵌 UI，也不是 marketplace lifecycle PASS 证据。

从同一个 CLI/客户端入口发现：

python skills/software-project-governance/infra/verify_workflow.py web-console --status

用户手动执行 /governance 是默认进入 Web UI 的入口。它应该启动或复用本地控制台，并输出 URL：

python skills/software-project-governance/infra/verify_workflow.py web-console --governance-entry

阶段性任务或 session 总结之后，agent 应追加这个无副作用入口：

python skills/software-project-governance/infra/verify_workflow.py web-console --summary-link

从当前仓库启动：

python skills/software-project-governance/infra/verify_workflow.py web-console --start

首次 checkout 如未安装前端依赖，显式加 --install：

python skills/software-project-governance/infra/verify_workflow.py web-console --start --install

然后打开命令输出的本地地址，通常是：

http://127.0.0.1:5173/

在 Codex/Claude 这类客户端里，手动执行 /governance 默认应启动或复用 Web 控制台，并给出本地 URL，方便后续用 Web UI 查看状态和继续交互。首次使用如果缺少依赖，按 CLI 输出的一次性 --install 路径安装。阶段性任务完成或 session 收尾时，agent 应该在总结之后追加 web-console --summary-link 的只读结果：如果 Web 控制台已经运行，就给出本地链接；如果未运行，只给出手动启动命令。CLI/客户端负责执行，Web 控制台负责状态、配置与后续交互。

安装

Claude Code

方式一：通过插件市场安装（推荐，两步）
/plugin marketplace add peterwangze/software-project-governance
/plugin install software-project-governance@spg

方式二：直接从 git URL 安装
/plugin install https://github.com/peterwangze/software-project-governance.git

方式三：克隆到本地后安装
git clone https://github.com/peterwangze/software-project-governance.git
/plugin install /path/to/software-project-governance

安装后，工作流入口会在后续会话中自动可用；但首次使用前仍必须先完成一次初始化，在你的项目根目录创建 .governance/ 治理文件。安装完成不等于已经可用完成。

Codex

git clone https://github.com/peterwangze/software-project-governance.git

当前仓库已提供 Codex 所需资产：.codex-plugin/plugin.json 和 skills/software-project-governance/SKILL.md。

但要注意两点：
1. Codex 的具体加载方式取决于你当前使用的 Codex 环境/插件机制，不是所有环境都等价于 Claude Code 的 /plugin install
2. 首次使用前同样要先初始化项目治理文件，否则后续状态、Gate、verify 都没有项目事实源

Codex 入口采用自包含 skill：skills/software-project-governance/SKILL.md 内嵌核心规则，详细规则从同目录 references/ 按需读取；项目运行数据写入你当前项目根目录 .governance/。

如果你当前使用的 Codex 环境不能直接消费 .codex-plugin/plugin.json，先把它视为插件资产包，再按该环境支持的 skill/plugin 加载方式接入。当前仓库提供的是可消费资产，不是对所有 Codex 运行环境都统一的一键安装命令。

首次进入后，优先完成初始化，再开始日常使用。没有初始化时，不建议直接运行状态类命令。

Gemini CLI

Gemini 当前走最薄项目投影，不维护第二套 workflow 规则。项目入口建议使用 GEMINI.md 指向：

skills/software-project-governance/SKILL.md

验证顺序：

python adapters/gemini/launch.py
python skills/software-project-governance/infra/verify_workflow.py gemini-auth-preflight
GEMINI_CLI_TRUST_WORKSPACE=true python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent gemini --timeout 180

当前边界：本机 Gemini CLI target-cwd read E2E 已在 2026-06-11 PASS/DEGRADED；headless 自动化需要设置 GEMINI_CLI_TRUST_WORKSPACE=true 或通过交互式信任当前目录。不要把 GEMINI.md 投影写成 Gemini plugin marketplace、official approval、marketplace approval 或 universal/full runtime support。

opencode
opencode 当前使用 AGENTS.md 或平台配置的 instruction file 指向同一个 skill 入口：

skills/software-project-governance/SKILL.md

验证顺序：

python adapters/opencode/launch.py
python skills/software-project-governance/infra/verify_workflow.py opencode-provider-preflight
python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent opencode --timeout 90

当前边界：本机 opencode target-cwd E2E 为 PASS/DEGRADED；provider/model preflight 仍然必须保留，避免未来把 provider 配置错误包装成 workflow failure 或 universal support。

DeepSeek Harness (dsh)

dsh 的标准扩展机制是 dsh plugin（pnpm 转发——add 的参数就是 pnpm 包规格），另有 agent preset 机制（roster 按优先级扫描已配置根 + ${DSH_HOME}/.agent-presets/ 用户根，先命中的根优先）。本仓库提供 dsh 插件包（package.json + cordis.patch.yml bundle 层，包内预设负载 agent-presets/governance/ = 组合模板 + preset.yml）+ 可选的 launch.py 预设渲染 + 薄项目指针，不维护第二套 workflow 规则，也不复制共享核心（skills/、commands/、agents/ 始终是包内唯一事实源，渲染为绝对路径引用）。

方式一（推荐）：dsh plugin 标准命令——一条命令完整安装（bundle + 预设）

前置要求：dsh ≥ 0.1.2-rc.1（预设随 bundle 激活的版本边界；≤0.1.1-rc.2 请用方式二）、pnpm（dsh plugin 转发依赖）、github: 形式另需 git + 网络；方式二与全部验证命令需 Python 3（命令名 python，部分 Linux/macOS 发行版为 python3）。Windows/macOS/Linux 的命令均同形（隔离验证片段已按 shell 标注）。

本地检出目录，符号链接（推荐——改码后重启 profile 即生效）
dsh plugin --profile web add link:/path/to/software-project-governance
本地快照备选（内容寻址，升级需 remove + add）
dsh plugin --profile web add file:/path/to/software-project-governance
从 GitHub 安装（需要 git + 网络）
dsh plugin --profile web add github:peterwangze/software-project-governance

升级 / 卸载
dsh plugin --profile web update @peterwangze/software-project-governance-plugin
dsh plugin --profile web remove @peterwangze/software-project-governance-plugin

安装后重启 DSH（dsh web）——bundle 层在 profile 启动时生效（boot-time，非 HMR），随后：

1. 「治理协调器」预设出现在预设选择器中〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕——插入的宿主行在开机时把包内模板渲染进 ${DSH_HOME}/.agent-presets/governance/（用户根）：roster 按根优先级扫描，用户根即第一个 user-trust 根，因此设置页显示为自定义预设（可删除、可打开目录，不是「内置」）；渲染按包版本号幂等（版本未变不写），失败只 warn 不抛（抛会打断 dsh 启动）。
2. 治理 skills 与 /governance 命令投影在该预设的会话中可用——仅在治理预设的会话中；其它预设（如 standard）的会话不含治理技能（这是 FIX-310 的核心行为目标）〔static: 规则级推导 —— 包内 agent-presets/governance/agent.cordis.yml.template 的 customSkillDirs 渲染为包内绝对路径 + 该预设自身的行；无会话级执行证据〕。⚠️ 该作用域的真机确认仍未完成（见 docs/release/release-checklist-0.80.0.md §真机验收面），在用户真实 dsh 上验证前不应据此宣示。（旧文案曾称「该 profile 的每个会话中可用」——那是 FIX-310 之前宿主平面全局注册时代的语义，已随宿主行 UPDATE 一并退役。）

框架边界（DEC-187 I-1/I-2/I-3，DEC-188 ② 澄清判据）：cordis.patch.yml 只有一条 - insert:，只命名本包自己的行，不改任何宿主行（无 UPDATE、无 !!js 自定位、无 trust: system 根、无宿主平面 provider/服务/工具注册）。机检判据 = 安装前后既有宿主行的存在性/config/disabled 与任何宿主平面注册表内容零变化、组合 entry 列表恰多一行且该行只命名本包——不是「与未安装时逐字节等价」（那一行正是官方 dsh plugin add/remove/update 的交付载体）。
预设落在用户根：设置页显示为自定义预设，提供删除与打开目录；删除后下次启动会重新渲染（除非同时 dsh plugin remove 撤回 bundle 行）。customSkillDirs 是绝对路径，因此不存在「副本脱离包后 skill 目录为空」的旧问题。整体移除走 dsh plugin remove（撤回 bundle 行）+ 删除用户根目录；手工装入的副本用 python adapters/dsh/launch.py --uninstall。

方式二（可选）：launch.py 预设直装（用户根副本 / 不依赖 bundle / 旧版 dsh 回退）

1. 预览（解析出的 DSH_HOME + 计划写入清单，零副作用——先跑这个）
python adapters/dsh/launch.py --install --dry-run

2. 渲染 governance 预设（persona = Coordinator bootstrap；注册仓库 skills/ + adapters/dsh/skill-shims/ 为绝对路径 skill 根；
仅写 4 个文件到 ${DSH_HOME}/.agent-presets/governance/（agent.cordis.yml + preset.yml + 两个标记），不删除、不触碰其他任何配置）
python adapters/dsh/launch.py --install

3. 项目级激活（写入薄 AGENTS.md，dsh 自动注入工作区会话）
python adapters/dsh/launch.py --bootstrap-project

4. 验证
python adapters/dsh/launch.py
python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters

0.81.0 起写入守卫（行为变更 B-2）：--install / --sync / --uninstall 在真实 home 形态下（DSH_HOME 未设 / 空串 / 空白，或解析为 ~/.dsh、~/.dsh 的子目录）一律 exit 2 + [REFUSED]——真实环境手工安装 MUST 先把 DSH_HOME 重定向到临时目录（拒绝面覆盖任何解析后落在真实用户 home 之下、含其父目录的 DSH_HOME）；--dry-run 是只读预览，仍放行。详见 docs/release/feature-flags-0.81.0.md §2。〔static: 0.81.0 写入守卫 adapters/dsh/launch.py write_side_refusal + 发布门禁测试；本段编辑未重跑拒绝路径〕

安装后：启动 dsh 会话选择「治理协调器」预设，或在被治理项目目录内开任意预设会话（由 AGENTS.md 激活）。用户输入 /governance 即加载统一治理入口（dsh 的 /name 手势加载同名 skill）〔live-session: 2026-07-08 真实 dsh 会话 0.1.0-rc.6 /name skill 加载验证〕〔isolation: 2026-09-05 dsh 0.1.2-rc.1 链路复验〕。

管理动作对称表（安装 / 升级 / 降级 / 卸载）

dsh 侧有两个安装面，各自有官方对称命令：

| 动作 | bundle 层（dsh plugin 官方命令） | governance 预设（launch.py） |
|------|-----------------------------------|-------------------------------|
| 安装 | dsh plugin --profile web add link:（或 file: / github:peterwangze/software-project-governance）+ 重启 | python adapters/dsh/launch.py --install（先加 --dry-run 预览） |
| 升级 | dsh plugin --profile web update @peterwangze/software-project-governance-plugin + 重启；link: 形式直接 git pull + 重启；file: 形式为 remove + add | git pull 后 python adapters/dsh/launch.py --sync |
| 降级 | dsh plugin remove 后 add github:peterwangze/software-project-governance#v（pnpm git ref 语义）；link: 直接 git checkout v + 重启 | git checkout v 后 launch.py --install（覆盖式重装） |
| 卸载 | dsh plugin --profile web remove @peterwangze/software-project-governance-plugin + 重启 | python adapters/dsh/launch.py --uninstall（可先 --dry-run 预览） |

关键边界：dsh plugin remove 管理 profile 的 pnpm 包/bundle 层——在 dsh ≥ 0.1.2-rc.1 上它会连包内预设一起移除（与 dsh plugin add 对称）。但它永远不触碰 ${DSH_HOME}/.agent-presets/ 用户预设根：经 launch.py --install 装入用户根的预设，其卸载路径是 launch.py --uninstall；对一个从来不是 pnpm 依赖的预设执行 dsh plugin remove @peterwangze/... 会报 ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS。

其他 agent 侧的管理动作对称性（有官方命令的用官方命令；无包管理器的平台按投影指针模型对称）：

| Agent | 安装 | 升级 | 降级 | 卸载 |
|-------|------|------|------|------|
| Claude Code | /plugin marketplace add + /plugin install software-project-governance@spg | /plugin marketplace update 后更新插件 | 从旧版本 git URL 重装 /plugin install | 宿主 /plugin 命令面卸载（以 /plugin 帮助为准） |
| zcode | 同 Claude 协议（/plugin marketplace add + /plugin install） | 同上 | 同上 | 同上 |
| Codex / Gemini CLI / opencode | 无官方包管理器——克隆仓库 + 平台投影指针（AGENTS.md / GEMINI.md 等） | git pull（指针不变） | git checkout v | 删除投影指针（可选删除克隆目录） |

安全验证边界（不要对真实 ~/.dsh 做“安装验证”）

预览用 --dry-run；需要真实执行安装/升级验证时，一律用重定向的临时 DSH_HOME（2026-09-05 在 dsh 0.1.2-rc.1 + pnpm 11.22.0 隔离复验 link:/file: 两种 plugin add 与 launch.py 预设安装，真实 home 零写入；全部验证在 Windows 上执行，非 Windows 未验证；github: 形式打包语义与 file: 同构——但 v0.79.0/v0.80.0/v0.81.0 三个 tag 均已推送（v0.80.0 已于 2026-09-12 发布，peel 71f73eb；补推义务见 docs/release/release-checklist-0.81.0.md §M-8 收尾义务），GitHub 侧 master 现为 0.81.0（e376ddf），github: 安装形态对三个 tag 均可用；本地 link:/file: 是等效路径）〔isolation: link:/file: 2026-09-05, Windows-only〕〔static: github: 形态——打包语义推理，未执行安装验证（RISK-049 披露）〕：

宣示验证等级（RISK-049 披露，FEAT-014）：登记在 ADAPTER_CLAIM_REGISTRY 的 dsh 宣示（当前 4 类：会话投影 / 预设清单 / /governance 手势 / 安装形态边界）逐条标注验证等级——live-session = 真实用户会话活体验证（标注日期）；isolation = 隔离环境复验（重定向 home/临时目录，零真实 home 写入，标注日期）；static = 静态检查/推理验证——无执行证据，显式标注未执行验证。Check 28t（check-governance）对该注册表映射做机器核验；本节中注册表之外的其他表述不在该核验范围内。

PowerShell（DSH_HOME 必须与后续命令同进程内联设置，防止宿主环境变量泄漏回真实 home）
$env:DSH_HOME = Join-Path $env:TEMP "dsh-verify-"; New-Item -ItemType Directory $env:DSH_HOME | Out-Null
python adapters/dsh/launch.py --install
dsh plugin --profile web add link:/path/to/software-project-governance
Remove-Item Env:\DSH_HOME   # 用完清理临时目录

当前边界：本适配器于 2026-07-08 在真实 dsh 会话（dsh --version = 0.1.0-rc.6）中完成编写与验证——原生 skill/subagent/ask_user_question/tool_calling/git_hooks 全部可用，生成的预设通过 agentPresets.standingKeyFor 挂载校验；2026-09-05 在 dsh 0.1.2-rc.1 + pnpm 11.22.0 隔离环境复验插件安装与预设生成链路。browser 自动化与 MCP 仍是 host-dependent（degraded）。这是 runtime-verified 适配，不是 dsh 官方收录、marketplace approval 或 universal/full runtime support。

zcode

zcode 新版运行时复用了 Claude 插件市场协议，支持通过 marketplace add + plugin install 两步安装：

方式一：通过插件市场安装（推荐，两步）
/plugin marketplace add peterwangze/software-project-governance
/plugin install software-project-governance@spg

方式二：直接从 git URL 安装
/plugin install https://github.com/peterwangze/software-project-governance.git

zcode 读取 .claude-plugin/marketplace.json（市场清单）和 .zcode-plugin/plugin.json（插件元数据）。0.62.0 起，0.56.0 的逆向 seed-hash 本地植入工具 project/zcode-local-load.py 已废弃移除（DEC-093）——新版 zcode 原生支持市场安装，不再需要逆向耦合。

当前边界：这是协议一致性安装，不是 zcode 官方收录或审核批准。RISK-036（官方收录准备）继续打开。

兼容观察平台（Cursor、Copilot coding agent、Cline、Windsurf/Cascade、Kiro）

这些平台在 0.47.0 只作为 compatibility/research rows。它们都有自己的 rules、custom instructions、memories 或 steering surface，可作为后续薄投影候选；但当前没有 adapter manifest、没有 target-cwd E2E、没有 runtime PASS。不要把这些兼容方向理解为“现在已经存在与 Claude Code 同等级的一键安装入口”。
SKILL.md 不是“要求 agent 顺序扫描整个仓库根目录”的索引文件；它是自包含入口，只依赖：
- skills/software-project-governance/SKILL.md（入口，内嵌核心规则）
- skills/software-project-governance/core/stage-gates.md
- skills/software-project-governance/core/lifecycle.md
- 你项目中的 .governance/（活跃治理记录）

如果你的 agent 不能稳定满足上面 4 个条件，就说明当前更适合走兼容路线，而不是直接按 README 当成现成产品入口使用。

唯一命令

安装后，只需记住一条命令：

/governance

这条命令会根据当前项目状态自动决策：

| 你的项目状态 | /governance 自动做的事 |
|-------------|------------------------|
| 首次使用（无 .governance/） | 引导初始化——收集项目信息 → 创建治理文件 |
| 会话恢复（上次有未完成工作） | 恢复遗留任务 + 待确认决策 + 活跃风险 |
| 异常检测（hook 缺失等） | 自动诊断 → 一键修复 |
| 日常状态查看 | 展示完整治理面板（阶段/Gate/任务/风险） |
| 工作流版本更新 | 自动升级 bootstrap + 补全缺失结构 |

所有场景，一条命令，零记忆负担。

5 分钟开始

先拿到一个本地信任信号，再理解完整治理模型。最短 happy path 是：运行 /governance 或 status，看到 Delivery Trust Snapshot；再用本地 demo harness 复核这个首屏信号。

第一步：看到 Delivery Trust Snapshot

首次使用时，先初始化并看到快照，再谈完整阶段、证据和发布治理。

在 Claude Code 中直接运行：

/governance

如果你的环境能直接显示 status，status 输出里的 Delivery Trust Snapshot 也是同一个第一信号。它会用很短的字段告诉你：当前目标、阶段、Gate/setup 状态、风险、证据、下一步动作、预设建议、验证命令，以及不得过度宣称的边界。

首次运行会自动检测到项目尚未初始化，引导你完成：
1. 输入项目名称和目标
2. 确认项目阶段（新项目/已有项目）
3. 选择治理强度（lite/standard/strict）
4. 自动创建 .governance/ 治理文件

第二步：跑本地 demo-only 验收

这个 demo path 不需要 external credentials，也不访问外部服务；它只验证本地 first-run snapshot 是否具备必要字段：

python skills/software-project-governance/infra/verify_workflow.py first-run-demo --assert-snapshot

Delivery Trust Snapshot 是第一个 trust signal：它证明工作流能把“已知事实、缺失证据、下一步动作和边界声明”摆在你面前。它不是官方批准、marketplace approval、universal/full runtime support，也不是 1.0.0 production-ready 声明。

外部 first-session measurement 与这个本地 demo 分开记录。当前 0.43.0 measured state 是 local_demo=PASS、external_pilot=NOT_MEASURED，见 first-session measurement evidence。

首次预设建议：

| 预设 | 首次适合 | 优化目标 |
|------|----------|----------|
| lite | 个人项目、MVP、想最快看到首个快照 | 少提问、快启动 |
| standard | 团队项目、正式产品、常规交付 | 平衡证据、Gate、风险和审查边界 |
| strict | 高风险、合规、发布敏感项目 | 更严格的证据和审批纪律 |

Pack 是能力模块，profile 是治理强度预设。profile 仍然只有 lite / standard / strict；0.44.0 当前采用 registry-first、no physical split，不要求用户在首次运行时理解或选择所有模块。

| 预设 | 默认起步 pack | 后续何时增加 |
|------|---------------|--------------|
| lite | governance-core | 当 AI 产出质量需要可执行约束时，再加入 quality-gates |
| standard | governance-core, quality-gates, release-governance, agent-team | 只有在审计性、适配器和 manifest 纪律值得额外上下文成本时，再加入 enterprise |
| strict | governance-core, quality-gates, release-governance, agent-team, enterprise | 保持全部 pack，并把任何 degraded runtime 当作发布风险处理 |

Pack 归属不是完成证据。pack enabled 不等于任务证据存在、独立审查通过、质量门禁通过、发布门禁通过、官方批准、marketplace approval 或 universal/full runtime support verified。

如果你的环境暂不支持 slash command，就直接告诉 agent 以上信息，让它按 skills/software-project-governance/SKILL.md 的规则帮你初始化。

仓库里已有的 .governance/ 是本项目自己的运行样例，不是你的初始化模板。 不要直接复制仓库根目录下已有的治理记录来当你的项目初始状态。

新项目

1. 告诉你的 agent："我要开始一个新项目，项目目标是 XXX"
2. 工作流自动从立项阶段开始，引导你明确目标、范围和关键决策
3. 每推进一个阶段，agent 会自动检查是否达到质量标准

已在进行的项目

1. 告诉你的 agent："我的项目目前在开发阶段，想接入治理工作流"
2. 工作流会要求你补充最少的信息（当前状态、关键决策、已知风险）
3. 之前的阶段自动标记为"已通过"，不需要补齐历史记录
4. 立即从当前阶段开始治理

只用某个功能

不需要加载全流程。你可以直接告诉 agent：

- "帮我做一次技术方案评审" → 加载技术评审 checklist
- "帮我做 Code Review" → 加载 Code Review 规范
- "帮我做发布 checklist" → 加载发布检查清单
- "帮我做项目复盘" → 加载回顾会议模板

项目规模选择

安装后第一次使用，工作流会问你的项目规模：

| 选择 | 适合 | 工作流做什么 | 你需要做什么 |
|------|------|------------|------------|
| 轻量 | 个人项目、MVP、探索 | 只跟踪核心阶段，最少记录 | 几乎不管，只在关键节点确认 |
| 标准 | 团队项目、正式产品 | 全流程 11 阶段，完整记录 | 方向决策和质量审核 |
| 严格 | 大型项目、合规系统 | 全流程 + 双重证据 + 不允许跳步 | 每个决策审核 + 审批 |

不确定选哪个？先选"标准"，随时可以调整。

日常体验

工作流自动做的事（不打扰你）

- 记录每个任务完成后的证据
- 检查 Gate 是否通过
- 跟踪风险状态变化
- 更新项目状态面板
- 在阶段转换时提醒你补齐必要记录

需要你做的事

- 方向决策：多条路线时选择走哪条
- 需求澄清：确认你到底要做什么
- 质量审核：确认产出物是否满足要求

你不会被打扰的事

- 记录更新、文件编辑、状态跟踪——全自动
- Gate 通过时不会打断你
- 两个紧密关联的任务之间不会停下来请示

覆盖的项目阶段

立项 → 调研 → 技术选型 → 环境搭建 → 架构设计 → 开发 → 测试 → CI/CD → 发布 → 运营 → 维护

每个阶段有独立的子工作流，包含：进入条件、活动清单、产出标准、退出检查。你可以从任意阶段开始。

验证

推荐方式（在 agent 内部）：运行 /governance，异常时自动触发诊断修复。

手动方式（在终端中）：

python skills/software-project-governance/infra/verify_workflow.py              # 完整校验
python skills/software-project-governance/infra/verify_workflow.py status       # 项目状态
python skills/software-project-governance/infra/verify_workflow.py gates        # 所有 Gate

内部文档

以下文档供工作流开发者和贡献者参考，普通用户不需要阅读：

- 协议层定义
- 生命周期规则
- Gate 门禁规则
- Profile 配置
- 中途接入协议
- 企业实践经验
- 产品形态设计