Software Project Governance
AI coding delivery trust layer for evidence-backed planning, review, risk, quality, and release control.
Software Project Governance helps AI coding agents keep delivery trustworthy while you stay focused on product and technical decisions. It is designed for marketplace reviewers, AI coding users, and teams who need a repeatable way to stop drift, missing evidence, weak review loops, and premature release claims.
Marketplace Review Ready
Use this workflow when your AI coding setup needs:
- Evidence-backed delivery: every meaningful task can carry facts about what changed, why it changed, how it was verified, and what remains risky.
- Gate and risk control: stage gates, task status, risks, decisions, and release readiness stay connected instead of living in scattered chat memory.
- Reviewer separation with degraded-mode honesty: the workflow distinguishes real independent review from degraded or environment-dependent execution, and does not present every agent as fully supported.
- 5-minute orientation for new users: start with
/governance, initialize .governance/, then let the agent resume state, check gates, and surface only critical decisions.
1.0.0 Readiness Boundary
0.57.0 packages the 0.55.0 Dynamic Lifecycle migration preview and external validation archive, the 0.55.1 Web console CLI/client entry patch, the 0.55.2 passive Web summary entry patch, the 0.55.3 governance-entry correction, the 0.56.0 zcode plugin marketplace adapter, the FIX-151 Web console real-data dashboard patch (0.56.1), and the AUDIT-121 architecture degradation audit archive (no functional code change). It is not the 1.0.0 release. 0.57.0 is a documentation/governance-only release: it archives the full-project architecture degradation diagnosis (docs/requirements/architecture-degradation-audit-0.57.0.md, F1-F6 facts: the verify_workflow.py God Module at 20,294 lines, the missing modern engineering infrastructure, the source/projection duplication, the command-surface redundancy, the self-evolution residue, and the architecture-health stewardship gap), adds a technical-debt ledger (skills/software-project-governance/core/technical-debt-ledger.md, TD-001006), cleans up root-directory residue (nul, _fix_030_reconstruct.py), and plans the subsequent refactor roadmap (0.58.0 ArchGuard as an independent capability version, 0.59.00.64.0 progressive per-domain split of verify_workflow.py). 0.57.0 does not modify verify_workflow.py functional code, does not implement ArchGuard, does not split any module, and does not introduce lint/type infrastructure. The release keeps the dry-run-only dynamic-lifecycle-migration --target <path> --dry-run preview, the migration guide, the python_game chapter-flow validation archive, and the shitu non-game validation archive from 0.55.0. 0.55.1 added web-console --status and web-console --start [--install]; 0.55.2 added web-console --summary-link for read-only task, phase, and session summaries; 0.55.3 restores the intended product entry so manual /governance starts or reuses the local Web console through web-console --governance-entry, then reports the URL for follow-up Web UI interaction; 0.56.0 adds the zcode native plugin surface (.zcode-plugin/, top-level package.json) and a one-shot project/zcode-local-load.py tool so the plugin can run in the local zcode installation; 0.56.1 fixes the Web console dashboard to read real governance data instead of hardcoded mock values, adds a web/server.py API server and web/vite.config.js proxy, makes all dashboard buttons functional, and keeps the dashboard a read-only local companion. classic-phase-gate remains the active/default compatibility preset, dynamic-flow-gate remains inactive/non-default and opt-in only, and no project is migrated by this release. The external validations remain intentionally conservative: both dry-run previews reached READY_FOR_REVIEW, but installed-state validation still has target-native blockers, and non-game preset generalization remains partial because shitu preview flow units still come from the python_game_10_chapters example. RISK-036, RISK-037, and RISK-039 remain open: no official approval, no marketplace approval (the zcode adapter proves local load/runtime only; it is not submitted to or approved by the zcode official marketplace), no two-real-project external validation full PASS, no Codex Desktop lifecycle PASS, no project migration, no ArchGuard implementation, no RISK-036 closure, no RISK-037 closure, no RISK-039 closure, and no 1.0.0 production-ready claim. 0.62.0 update (FIX-167, DEC-093): the 0.56.0 reverse-engineered project/zcode-local-load.py seed-hash tool has been removed — newer zcode runtimes ship a marketplace chain and the plugin now installs via the shared Claude/zcode marketplace protocol (/plugin marketplace add peterwangze/software-project-governance). This is protocol-conformant installability, still not zcode official curation or approval; RISK-036/RISK-037/RISK-039 remain open.
Mainstream Agent Loading
0.47.0 makes the current loading paths explicit for mainstream AI coding agents. This is loading readiness, not official approval, marketplace approval, universal/full runtime support, or Codex Desktop marketplace-management E2E PASS. See the 0.47.0 scope note in docs/requirements/mainstream-agent-loading-0.47.0.md and the public runtime facts in docs/requirements/runtime-readiness-matrix-0.43.0.md.
Tier 1 loading guide:
| Agent | Load or install path | First verification | Current boundary |
|---|
| Claude Code | Add this repo as a Claude plugin marketplace, then install software-project-governance@spg. | python adapters/claude/launch.py and python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters --runtime | Claude target-cwd read use case is PASS/DEGRADED in local evidence. This is not official marketplace approval. |
| Codex | Use .agents/plugins/marketplace.json, .codex-plugin/plugin.json, AGENTS.md, and skills/software-project-governance/SKILL.md as the Codex plugin/project guidance package. | python -m json.tool .agents/plugins/marketplace.json, python -m json.tool .codex-plugin/plugin.json, python adapters/codex/launch.py, and python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent codex --timeout 180 | Codex CLI headless target-cwd read E2E is PASS/DEGRADED as of 2026-06-11. This is still not Codex Desktop marketplace-management lifecycle PASS. |
| Gemini CLI | Use a thin GEMINI.md project context pointer to skills/software-project-governance/SKILL.md; custom commands, MCP, and extensions remain separate extension points. | python adapters/gemini/launch.py, then 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 is PASS/DEGRADED as of 2026-06-11 when headless workspace trust is enabled. No Gemini plugin marketplace claim. |
| opencode | Use AGENTS.md or configured opencode instructions to point at skills/software-project-governance/SKILL.md. | python skills/software-project-governance/infra/verify_workflow.py opencode-provider-preflight and python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent opencode --timeout 90 | opencode target-cwd runtime E2E is PASS/DEGRADED in local evidence; provider/model preflight still guards future regressions. |
| Chrys | Chrys auto-loads AGENTS.md and CLAUDE.md as native context, plus native load_skill for skills/software-project-governance/SKILL.md. |
Tier 2 compatibility and research rows:
| Agent | Loading surface to watch | 0.47.0 status |
|---|
| Cursor | Project/user/team rules and AGENTS.md style project instructions | Compatibility reference only; no adapter manifest or runtime PASS. |
| GitHub Copilot coding agent | Repository custom instructions and AGENTS.md custom instructions | Compatibility reference only; no adapter manifest or runtime PASS. |
| Cline | Markdown rules such as Cline rules files | Compatibility reference only; no adapter manifest or runtime PASS. |
| Windsurf/Cascade | Workspace rules and memories | Compatibility reference only; no adapter manifest or runtime PASS. |
| Kiro | Workspace steering files such as .kiro/steering/ | Compatibility reference only; no adapter manifest or runtime PASS. |
Claude Code:
/plugin marketplace add peterwangze/software-project-governance
/plugin install software-project-governance@spg
Alternative Claude paths:
/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) plugin install — dsh plugin is a thin pnpm forwarder, so the add spec is a pnpm package spec (same style as the dsh-novel-writing plugin). Prerequisites: dsh ≥ 0.1.2-rc.1 (the version boundary where the preset activates with the bundle; on ≤0.1.1-rc.2 use the optional launch.py path below), pnpm, and for the github: form git + network; the launch.py path and all verification commands need Python 3 (python; some Linux/macOS distributions use python3).
# local checkout, live link (recommended for contributors — code edits apply on profile restart)
dsh plugin --profile web add link:/path/to/software-project-governance
# local snapshot alternative (content-addressed; upgrading needs remove + add)
dsh plugin --profile web add file:/path/to/software-project-governance
# from GitHub (needs git + network)
dsh plugin --profile web add github:peterwangze/software-project-governance
# upgrade / uninstall
dsh plugin --profile web update @peterwangze/software-project-governance-plugin
dsh plugin --profile web remove @peterwangze/software-project-governance-plugin
Restart the dsh web profile after installing — the bundle layer applies at profile boot (boot-time, not HMR). The inserted row then renders the packaged preset into ${DSH_HOME}/.agent-presets/governance/, so the governance preset (「治理协调器」) appears in the preset roster〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕, and the governance skills + /governance command projections load in that preset's sessions only — sessions on other presets (e.g. standard) carry no governance skills (this scoping is FIX-310's core behavioural goal; its real-machine confirmation is still pending — see the release checklist's acceptance face). Delivery is a pure insert: cordis.patch.yml adds ONE row naming this package only, so dsh --profile web --dump-config differs from the unpatched composition by that row alone — every dsh / dsh-web-app row keeps its config and disabled state (DEC-187 I-1/I-2/I-3 as clarified by DEC-188 ②; no host row is patched, no !!js self-location, no trust: system root). That row renders agent-presets/governance/agent.cordis.yml.template into ${DSH_HOME}/.agent-presets/governance/, i.e. the user preset root: the settings page therefore shows a custom preset with delete and open-folder available, and the composition's customSkillDirs are absolute paths into the package, so no copy re-anchoring can empty the skill catalog. Removal: dsh plugin remove withdraws the bundle row; delete the user-root preset directory to remove the last rendered copy (a later dsh boot re-renders it — see the note below).
Optional manual preset-side path (adapters/dsh/launch.py) — same rendered result without the bundle row (preset-only install, offline checkout, or scripted installs):
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)
Since 0.81.0 these write paths refuse a real home (behaviour B-2, docs/release/feature-flags-0.81.0.md section 2): --install / --sync / --uninstall exit 2 with [REFUSED] unless DSH_HOME is explicitly set to a directory outside your real home tree (~/.dsh (unset or blank counts as the real home), so a deliberate manual install MUST redirect DSH_HOME to a temporary directory; --dry-run stays a read-only preview and is still allowed. 〔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〕
Safe verification boundary (do not "verify" against your real ~/.dsh): preview with --dry-run, then run install/upgrade checks against a redirected 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
Both forms were re-verified this way (temp-dir DSH_HOME, zero writes to the real home) on dsh 0.1.2-rc.1 + pnpm 11.22.0, 2026-09-05 — all verification ran on Windows; non-Windows is unverified〔isolation: link:/file: 2026-09-05, Windows-only〕〔static: github: form — packaging semantics by reasoning, not install-verified (see RISK-049)〕. Note on github:: v0.79.0 and v0.80.0 are tagged and pushed (v0.80.0 peels to 71f73eb; 0.80.0 released 2026-09-12 — docs/release/release-checklist-0.80.0.md) and pushed to the remote (M-7 of 0.81.0 completed the back-push — the count of unpushed tags/commits is disclosed in docs/release/release-checklist-0.79.0.md and …-0.81.0.md §M-8 收尾义务; the M-7 push carries the v0.79.0/v0.80.0 back-push obligation). GitHub's master now serves 0.81.0 (e376ddf) and the github: install form is available for v0.79.0/v0.80.0/v0.81.0; a local checkout (link:/file:) remains an equivalent path.
Claim evidence levels (RISK-049 disclosure, FEAT-014): the dsh claims registered in ADAPTER_CLAIM_REGISTRY (4 claim classes — session projection / preset roster / /governance gesture / install-forms boundary) are annotated with their verification level — live-session = verified in a real user session (date cited); isolation = re-verified in an isolated/redirected environment (date cited); static = static/inspection reasoning only, explicitly labeled as not execution-verified. Check 28t (check-governance) machine-checks that registry mapping; statements in this dsh section outside the registry are not covered by it.
Symmetric lifecycle management (install / upgrade / downgrade / uninstall — official commands per surface):
# 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)
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<old-tag> + --install (overwrites in place)
Key boundary: dsh plugin remove manages the profile's pnpm bundle layer — on dsh ≥ 0.1.2-rc.1 that removes the whole package including the bundle-provided preset (the symmetric uninstall for a dsh plugin add install). It still never touches ${DSH_HOME}/.agent-presets/: a preset installed there via launch.py --install is uninstalled by launch.py --uninstall (or manual directory deletion), and dsh plugin remove on a preset that was never a pnpm dependency reports ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS.
Codex personal marketplace package:
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 and opencode thin project projections:
python adapters/gemini/launch.py
python adapters/opencode/launch.py
For every agent, load skills/software-project-governance/SKILL.md as the workflow entry and let runtime records live in the target project's .governance/ directory. Adapter and marketplace assets describe install and loading paths; they are not evidence of marketplace approval or universal runtime readiness.
Trust and Data Boundary
- The workflow writes project governance state to your project-local
.governance/ directory.
- It uses local files, git hooks, validation scripts, and agent-readable skills to keep delivery facts inspectable.
- The repository's own
.governance/ directory is a dogfood/sample runtime record, not a template to copy into your project.
- Adapter and marketplace assets describe install and loading paths; they are not evidence of marketplace approval or universal runtime readiness.
5-Minute Start
The first success path is intentionally small: get one local trust signal before learning the full governance model.
- Install through one of the paths above.
- Open your project root in your AI coding environment.
- Run
/governance; if your environment exposes status directly, the same first signal is the status output.
- Look for the Delivery Trust Snapshot: goal, stage, gate/setup status, risk, evidence, next action, preset guidance, verification signal, and no-overclaim boundary.
- For a local demo-only check that needs no external credentials, run:
python skills/software-project-governance/infra/verify_workflow.py first-run-demo --assert-snapshot
The snapshot is the first trust signal: it proves the workflow can show what it knows, what remains missing, and the next evidence-backed action. It is not a claim of official approval, marketplace approval, universal/full runtime support, or 1.0.0 production-ready status.
External first-session measurement is tracked separately from this local demo. The current 0.43.0 measured state is local_demo=PASS and external_pilot=NOT_MEASURED in the first-session measurement evidence.
Optional Local Web Console
The primary user interface remains your AI coding CLI or client: Claude Code, Codex, Gemini CLI, opencode, or another agent host. The web/ console is an optional local companion view for users who want a cleaner status surface while still driving work from the CLI/client.
Use it for local configuration, current status, evidence/risk scanning, and advanced maintenance visibility. It does not replace /governance, does not auto-run agent tasks, and is not evidence of Codex Desktop marketplace-management lifecycle PASS.
Discover it from the same CLI/client path:
python skills/software-project-governance/infra/verify_workflow.py web-console --status
Manual /governance is the default user entry into the Web UI. It should start or reuse the local console and print the URL:
python skills/software-project-governance/infra/verify_workflow.py web-console --governance-entry
Print the no-side-effect footer that agents should append after a task, phase, or session summary:
python skills/software-project-governance/infra/verify_workflow.py web-console --summary-link
Start it from this repository checkout:
python skills/software-project-governance/infra/verify_workflow.py web-console --start
On a first checkout, include dependency installation explicitly:
python skills/software-project-governance/infra/verify_workflow.py web-console --start --install
Then open the local URL printed by the command, usually:
http://127.0.0.1:5173/
In a CLI/client session, manual /governance starts or reuses the Web console by default so the user can keep interacting through a readable local dashboard. If dependencies are missing on first use, run the explicit install path shown by the CLI. After a task, phase, or session summary, the agent should append the read-only web-console --summary-link result: it reports the local URL if the console is already running, or the manual start command if it is not. Keep execution authority in the CLI/client; use the Web console for status, local configuration, and follow-up interaction.
First-run preset guidance:
| Preset | Use first when | What it optimizes for |
|---|
| lite | You want the quickest first run or a personal/MVP project | Minimal questions and a fast snapshot |
| standard | You are running team delivery or a normal product project | Balanced evidence, gates, risks, and review boundaries |
| strict | You are in regulated, high-risk, or release-sensitive work | Stronger evidence and approval discipline |
Packs are capability modules; profiles are governance intensity presets. Profiles stay lite / standard / strict, and the current 0.44.0 implementation is registry-first with no physical split.
| Preset | Default packs to start with | What to add later |
|---|
| lite | governance-core | Add quality-gates when AI output quality needs executable constraints |
| standard | governance-core, quality-gates, release-governance, agent-team | Add enterprise only when auditability and adapter/manifest discipline are worth the extra context |
| strict | governance-core, quality-gates, release-governance, agent-team, enterprise | Keep all packs enabled and treat any degraded runtime as a release risk |
Pack membership is not completion evidence. pack enabled does not mean task evidence exists, independent review passed, quality gates passed, release gates passed, official approval was granted, marketplace approval was granted, or universal/full runtime support is verified.
For full Chinese installation details and daily usage guidance, continue below.
中文详细说明
让 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。
但要注意两点：
- Codex 的具体加载方式取决于你当前使用的 Codex 环境/插件机制，不是所有环境都等价于 Claude Code 的
/plugin install
- 首次使用前同样要先初始化项目治理文件，否则后续状态、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），随后：
- 「治理协调器」预设出现在预设选择器中〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕——插入的宿主行在开机时把包内模板渲染进
${DSH_HOME}/.agent-presets/governance/（用户根）：roster 按根优先级扫描，用户根即第一个 user-trust 根，因此设置页显示为自定义预设（可删除、可打开目录，不是「内置」）；渲染按包版本号幂等（版本未变不写），失败只 warn 不抛（抛会打断 dsh 启动）。
- 治理 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<旧tag>（pnpm git ref 语义）；link: 直接 git checkout v<旧tag> + 重启 | git checkout v<旧tag> 后 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<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.mdskills/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 状态、风险、证据、下一步动作、预设建议、验证命令，以及不得过度宣称的边界。
首次运行会自动检测到项目尚未初始化，引导你完成：
- 输入项目名称和目标
- 确认项目阶段（新项目/已有项目）
- 选择治理强度（lite/standard/strict）
- 自动创建
.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/ 是本项目自己的运行样例，不是你的初始化模板。 不要直接复制仓库根目录下已有的治理记录来当你的项目初始状态。
新项目
- 告诉你的 agent："我要开始一个新项目，项目目标是 XXX"
- 工作流自动从立项阶段开始，引导你明确目标、范围和关键决策
- 每推进一个阶段，agent 会自动检查是否达到质量标准
已在进行的项目
- 告诉你的 agent："我的项目目前在开发阶段，想接入治理工作流"
- 工作流会要求你补充最少的信息（当前状态、关键决策、已知风险）
- 之前的阶段自动标记为"已通过"，不需要补齐历史记录
- 立即从当前阶段开始治理
只用某个功能
不需要加载全流程。你可以直接告诉 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
内部文档
以下文档供工作流开发者和贡献者参考，普通用户不需要阅读：
