软件项目治理 peterwangze/software-project-governance

软件项目治理

为 AI 编码交付提供信任层：用证据支撑规划、评审、风险、质量与发布控制。

软件项目治理帮助 AI 编码智能体让交付保持可信，让你专注在产品与技术决策上。它面向市场审核人员、AI 编码用户和团队，提供一套可重复的方法，用来阻止偏离、证据缺失、评审循环薄弱和过早宣称发布。

市场审核就绪

当你的 AI 编码环境需要以下能力时，就用这套工作流：

- 证据支撑的交付：每个有意义的任务都能携带事实——改了什么、为什么改、怎么验证、还剩哪些风险。
- 门禁与风险控制：阶段门禁、任务状态、风险、决策和发布就绪度保持关联，而不是散落在聊天记忆里。
- 评审者分离，并诚实对待降级模式：工作流区分真正的独立评审与降级执行或依赖环境的执行，不会把每个智能体都描述成完全受支持。
- 新用户 5 分钟上手：从 /governance 开始，初始化 .governance/，然后让智能体恢复状态、检查门禁，只呈现关键决策。

1.0.0 就绪边界

0.57.0 打包了 0.55.0 的动态生命周期迁移预览与外部验证归档、0.55.1 的 Web 控制台命令行/客户端入口补丁、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 <path> --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 seed-hash 工具已移除——较新的 zcode 运行时自带市场链路，插件现在通过共享的 Claude/zcode 市场协议安装（/plugin marketplace add peterwangze/software-project-governance）。这符合协议的可安装性，仍不代表 zcode 官方收录或批准；RISK-036/RISK-037/RISK-039 仍未关闭。

主流智能体加载

0.47.0 把当前主流 AI 编程智能体的加载路径讲清楚了。这里说的是加载就绪，不是官方认可，不是应用市场上架，不是通用/完整运行时支持，也不是 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 加载指南：

| 智能体 | 加载或安装路径 | 首次验证 | 当前边界 |
| 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 命令行无头 target-cwd 读取 E2E 是 PASS/DEGRADED。这仍然不是 Codex Desktop 应用市场管理生命周期的 PASS。 |
| Gemini 命令行 | 用一份简短的 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 命令行 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；服务商/模型预检仍会拦住以后的回归。 |
| DeepSeek Harness (dsh) | 标准插件安装（底层用 pnpm；推荐 link: 本地检出——代码实时生效，见下文 dsh 小节）：dsh plugin --profile web add link:/path/to/software-project-governance；也支持 file:（快照）和 github:peterwangze/software-project-governance。重启配置档以激活 bundle 层——在声明了 agent-preset 注册表的主机上，插入的那一行会原生注册预设（不写目录）；没有这一行的主机只会告警，什么都不写（DEC-366 ②）；两种情况都只在该预设的会话里加载治理技能和 /governance 命令投影（standard 等其他预设不带治理技能；这个作用域划分是 FIX-310 的核心行为目标，真机确认仍待完成）。协调者人格预设：原生主机在启动时通过公共注册表推导出来；对目录模型的主机，显式安装器会把 agent-presets/governance/agent.cordis.yml.template 写进 ${DSH_HOME}/.agent-presets/governance/（DSH_HOME 重定向到隔离目录），所以显式安装 + 重启后，governance 预设会出现在预设名册里〔隔离验证：2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，仅 Windows〕——用户预设根是第一个用户信任根，因此设置页把它显示为自定义预设（可删除、可打开文件夹，标签不是「内置」）。显式渲染器按包版本幂等，失败只告警；插入的那一行本身从不渲染目录（DEC-366 ②）。可选的手动路径（只装预设、离线、旧版 dsh）：python adapters/dsh/launch.py --install（先加 --dry-run 预览）渲染出字节完全一致的组合——write_side_refusal：真实用户根会被拒绝，退出码 2；只写重定向后的 DSH_HOME（隔离环境）。按项目激活：python adapters/dsh/launch.py --bootstrap-project <dir> 写一个精简的 AGENTS.md。 | dsh --profile <name> --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 的原生能力最强（原生 ask_user_question、subagent、tool_calling、git_hooks；/governance 加载命令 shim 技能）。只剩浏览器自动化和 MCP 依赖宿主。dsh 插件安装走官方 bundle 机制，不代表市场审核通过，也不代表通用运行时承诺。link:/github: 安装已于 2026-09-05 在隔离的 DSH_HOME 中、dsh 0.1.2-rc.1 + pnpm 11.22.0 上复验。 |
| 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）。 |
| Pi | pi 原生加载 AGENTS.md/CLAUDE.md 上下文文件，并实现 Agent Skills 规范。在 ~/.pi/agent/settings.json 中通过三个路径数组接入（skills/prompts -> 仓库的 skills/+commands/，可选的 extensions -> adapters/pi/extension，用于治理桥接工具）。 | python adapters/pi/launch.py 和 python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent pi --timeout 90 | 通过扩展桥接的 ask_user_question/dispatch_agent（tui/rpc 交互范围；无头模式会以 GOV_ASK_USER_HEADLESS 快速失败）；tool_calling 和 git_hooks 原生支持。运行时 E2E 待定——能力如实记录为 designed/degraded。 |

Tier 2 兼容性与调研行：

| 智能体 | 需关注的加载面 | 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 的 spec 就是 pnpm 包 spec（与 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）。

本地 checkout，实时链接（推荐贡献者使用——改代码后重启配置档即生效）
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 0.2+（原生派生，FEAT-102）：组合后的配置档声明了宿主机的 agent-preset 注册表时，插入的那一行不渲染目录。启动时，它在公开 loader 树上找到宿主机自己当前的 standard 声明，只追加两段内容增量（治理人格正文和本包的两个技能根），再通过公开的 agentPresets.register 服务注册结果。因此宿主机新增工具、重命名、禁用标记都会自行传播——升级 dsh 不再让预设失效——并且不会往 ${DSH_HOME} 下写任何东西；卸载只释放本包自己的注册。插入的那一行永远不渲染预设目录（DEC-366 ②）：原生注册是它唯一的交付面。四种不可用状态各报一条警告，且不写任何内容——absent（组合树里没有注册表行：目录模型的宿主机需要显式执行 launch.py --install，并把 DSH_HOME 指向隔离目录）、disabled（注册表行已组合但被禁用）、unreadable（无法枚举 loader 条目树）、ambiguous（没有唯一可合并的基础声明：缺失、重复或形状不安全）。〔runtime: 2026-10-20，隔离的 DSH_HOME（重定向的临时配置档，真实 link: bundle，dsh 0.2.1-rc.2）：roster 显示治理协调器，resolve 报告没有损坏行，会话组合出 governance，治理技能目录包含 software-project-governance 和命令 shims，而 standard 会话没有，${DSH_HOME}/.agent-presets 保持不存在；仅 Windows、单宿主机证据〕下面几段介绍留给运维和测试使用的显式渲染器（launch.py --install）。
安装完成后重启 dsh web 配置档——bundle 层在配置档启动时生效（启动时加载，不是 HMR）。显式渲染器（python adapters/dsh/launch.py --install，运行时把 DSH_HOME 重定向到隔离目录）会把打包好的预设写入 ${DSH_HOME}/.agent-presets/governance/，于是 governance 预设（「治理协调器」）会出现在预设列表中〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕，治理技能和 /governance 命令投影只在该预设的会话中加载——其他预设（例如 standard）的会话不带治理技能（这个作用域限定是 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/，也就是用户预设根目录：因此设置页会显示一个自定义预设，可删除、可打开文件夹；组合里的 customSkillDirs 是指向包内的绝对路径，所以不会因为复制后重新锚定而清空技能目录。移除：dsh plugin remove 撤回 bundle 行；删除用户根预设目录即可移除最后一份渲染副本（显式重装会重新创建它——见下方说明）。

可选的手动预设侧路径（adapters/dsh/launch.py）——不经过 bundle 行也能得到同样的渲染结果（仅预设安装、离线检出或脚本化安装）：

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 会以 2 退出并打印 [REFUSED]（~/.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，对真实 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: 形式 —— 打包语义靠推理，未做安装验证（见 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）会机器校验该登记表映射；本节中登记表之外的陈述不受其覆盖。

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

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<old-tag> (pnpm git-ref semantics); link: → git checkout v<old-tag> + restart

governance preset (launch.py, the user preset root)
python adapters/dsh/launch.py --install # install (add --dry-run to preview) — write_side_refusal: the real user root is refused with exit 2; only a redirected DSH_HOME (isolated env) is written
升级：先 git pull，再重启 dsh 完成原生注册；插入的那一行永远不会重新渲染出目录 —— 目录模型安装要用 launch.py --install 显式刷新，且必须重定向 DSH_HOME（--sync 只适用于隔离环境；真实用户根目录会被拒绝，退出码 2）
python adapters/dsh/launch.py --uninstall # 卸载 —— 精确删除 .agent-presets/governance/（加 --dry-run 可预览）；写入侧同样有守卫：真实用户根目录会被拒绝，退出码 2（仅限重定向的 DSH_HOME）
降级：git checkout v<old-tag> + 在重定向的 DSH_HOME 下执行 --install（真实用户根目录会被拒绝，退出码 2）；那一行永远不会渲染，显式重装只会原地覆盖

关键边界：dsh plugin remove 管理的是配置档的 pnpm bundle 层 —— 在 dsh ≥ 0.1.2-rc.1 上，它会删掉整个包，包括 bundle 提供的预设（这是 dsh plugin add 安装的对称卸载方式）。它依然不会碰 ${DSH_HOME}/.agent-presets/：通过 launch.py --install 装到那里的预设，要用 launch.py --uninstall 卸载（或手动删目录）；对一个从来不是 pnpm 依赖的预设执行 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

对每个智能体，都把 skills/software-project-governance/SKILL.md 作为工作流入口加载，并让运行时记录落在目标项目的 .governance/ 目录里。适配器和 marketplace 资产只描述安装与加载路径；它们不代表 marketplace 已批准，也不代表所有运行时都能用。

信任与数据边界

- 工作流把项目治理状态写入你项目本地的 .governance/ 目录。
- 它用本地文件、git 钩子、校验脚本和智能体可读的技能，让交付事实保持可检查。
- 仓库自带的 .governance/ 目录是 dogfood/示例运行时记录，不是让你复制进项目的模板。
- 适配器和 marketplace 资产只描述安装与加载路径；它们不代表 marketplace 已批准，也不代表所有运行时都能用。

5 分钟上手

第一条成功路径刻意做得很小：先拿到一个本地信任信号，再去学完整的治理模型。

1. 用上面任意一种方式安装。
2. 在 AI 编码环境里打开你的项目根目录。
3. 运行 /governance；如果你的环境直接暴露状态，同一个首个信号就是状态输出。
4. 找到 Delivery Trust Snapshot：目标、阶段、gate/setup 状态、风险、证据、下一步动作、预设指引、验证信号，以及「不过度声明」的边界。
5. 想在本机做一次纯演示检查、不需要任何外部凭据，运行：

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

快照是第一个信任信号：它证明工作流能说清自己知道什么、还缺什么、下一步该拿什么证据做什么。这不等于宣称已获官方批准、应用市场批准、通用/完整运行时支持，也不等于 1.0.0 生产就绪。

外部首次会话的测量与这个本地演示分开跟踪。当前 0.43.0 的测量状态是 local_demo=PASS、external_pilot=NOT_MEASURED，见首次会话测量证据。

可选的本地 Web 控制台

主要用户界面仍然是你的 AI 编程命令行或客户端：Claude Code、Codex、Gemini CLI、opencode，或其他智能体宿主。web/ 控制台是可选的本地辅助视图，适合想要更清爽状态面板、但仍从命令行/客户端驱动工作的用户。

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

从同一条命令行/客户端路径发现它：

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/
在命令行/客户端会话里，手动执行 /governance 默认会启动或复用 Web 控制台，让你能通过一个可读的本地面板继续交互。首次使用时如果缺少依赖，按命令行提示的显式安装路径执行。任务、阶段或会话总结完成后，智能体应追加只读的 web-console --summary-link 结果：控制台已在运行时，它报告本地 URL；未运行时，它报告手动启动命令。执行权留在命令行/客户端；Web 控制台用于查看状态、本地配置和后续交互。

首次运行预设指引：

| 预设 | 何时优先使用 | 它优化什么 |
| lite | 你想最快完成首次运行，或是个人/MVP 项目 | 最少提问，快速快照 |
| standard | 你在做团队交付或常规产品项目 | 证据、Gate、风险与评审边界之间的平衡 |
| strict | 你在受监管、高风险或对发布敏感的场景工作 | 更强的证据与审批纪律 |

pack 是能力模块；profile 是治理强度预设。profile 固定为 lite / standard / strict，当前 0.44.0 实现以注册表优先，没有物理拆分。

| 预设 | 起步默认 pack | 后续再加什么 |
| lite | governance-core | AI 输出质量需要可执行约束时，加 quality-gates |
| standard | governance-core、quality-gates、release-governance、agent-team | 只有当可审计性与 adapter/manifest 纪律值得多花上下文时，才加 enterprise |
| strict | governance-core、quality-gates、release-governance、agent-team、enterprise | 保持所有 pack 启用，把任何运行时降级都当作发布风险 |

pack 成员资格不是完成证据。pack enabled 不代表任务证据已存在、独立评审已通过、质量 Gate 已通过、发布 Gate 已通过、已获正式审批、已获市场审批，也不代表已验证通用/完整运行时支持。

完整的中文安装细节与日常使用指引，继续往下看。

中文详细说明

让 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）：行为协议自动化——智能体按协议纪律自动执行。本 README「一句话说明」「日常体验」中的自动承诺（「过程管理全自动」「自动记录证据」「自动检查 Gate」「工作流自动做的事」「记录更新、文件编辑、状态跟踪——全自动」等）与会话内智能体动作（自动升级 bootstrap + 补全缺失结构、自动创建 .governance/ 治理文件、自动标记阶段、自动检查质量等）均属本级——智能体按协议纪律自动推进并记录，不是系统后台触发。

- 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 预览；写侧守卫同 --sync：对真实用户根必拒 exit 2，仅限显式重定向 DSH_HOME 的隔离环境） |
| 升级 | dsh plugin --profile web update @peterwangze/software-project-governance-plugin + 重启；link: 形式直接 git pull + 重启；file: 形式为 remove + add | git pull 后：native 宿主重启即生效（row 只做登记/warn，不自动渲染）；目录模型安装用显式 launch.py --install（隔离 DSH_HOME，--sync 同守卫）覆盖重渲染 |
| 降级 | dsh plugin remove 后 add github:peterwangze/software-project-governance#v<旧tag>（pnpm git ref 语义）；link: 直接 git checkout v<旧tag> + 重启 | git checkout v<旧tag> 后 launch.py --install（覆盖式重装；同写侧守卫：真实用户根必拒 exit 2——在显式重定向 DSH_HOME 的隔离环境执行）。row 不再自动渲染，降级重装也没有「重启即重渲染」路径 |
| 卸载 | dsh plugin --profile web remove @peterwangze/software-project-governance-plugin + 重启 | python adapters/dsh/launch.py --uninstall（可先 --dry-run 预览；写侧守卫同 --sync：对真实用户根必拒 exit 2，仅限显式重定向 DSH_HOME 的隔离环境） |

关键边界：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<tag> | 删除投影指针（可选删除克隆目录） |

安全验证边界（不要对真实 ~/.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-<rand>"; 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 配置
- 中途接入协议
- 企业实践经验
- 产品形态设计