software-project-governance

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-001~006), 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.0~0.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 --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. DeepSeek Harness (dsh) · Standard plugin install (pnpm-backed; link: local checkout recommended — live code, see the dsh section below): dsh plugin --profile web add link:/path/to/software-project-governance; also file: (snapshot) and github:peterwangze/software-project-governance. Restart the profile to activate the bundle layer — on a host that declares the agent-preset registry the inserted row registers the preset natively (no directory written), and on a host without that row it only warns and writes nothing (DEC-366 ②); in either case the governance skills and /governance command projections load in that preset's sessions only (other presets such as standard carry no governance skills; this scoping is FIX-310's core behavioural goal and its real-machine confirmation is still pending). Coordinator persona preset: native hosts derive it at boot through the public registry; for directory-model hosts the explicit installer writes agent-presets/governance/agent.cordis.yml.template into ${DSH_HOME}/.agent-presets/governance/ (DSH_HOME redirected to an isolated directory), so the governance preset appears in the preset roster after that explicit install + restart 〔isolation: 2026-09-12 FIX-310 隔离 DSH_HOME 渲染复验，Windows-only〕 — the user preset root is the first user-trust root, so the settings page shows it as a custom preset (delete + open-folder available, label not 「内置」). The explicit renderer is idempotent per package version and warn-only on failure; the inserted row itself never renders a directory (DEC-366 ②). Optional manual path (preset-only install, offline, older dsh): python adapters/dsh/launch.py --install (add --dry-run first to preview) renders the byte-identical composition — write_side_refusal: the real user root is refused with exit 2; only a redirected DSH_HOME (isolated env) is written. Per-project activation: python adapters/dsh/launch.py --bootstrap-project writes a thin AGENTS.md. · dsh --profile --dump-config shows the @peterwangze/software-project-governance-plugin bundle layer; python adapters/dsh/launch.py --install --dry-run; python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters · dsh has the strongest native profile (native ask_user_question, subagent, tool_calling, git_hooks; /governance loads the command shim skill). Only browser automation and MCP remain host-dependent. The dsh plugin install is the official bundle mechanism, not a marketplace approval or universal runtime claim. link:/github: installs re-verified 2026-09-05 in an isolated DSH_HOME on dsh 0.1.2-rc.1 + pnpm 11.22.0. zcode · Add this repo as a plugin marketplace and install: /plugin marketplace add peterwangze/software-project-governance, then /plugin install software-project-governance@spg. zcode reuses the Claude marketplace protocol (.claude-plugin/marketplace.json + .zcode-plugin/plugin.json). · python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters · Protocol-conformant marketplace install. Not zcode official curation or approval. The 0.56.0 reverse-engineered local-load tool was retired in 0.62.0 (DEC-093). Pi · pi natively loads AGENTS.md/CLAUDE.md context files and implements the Agent Skills spec. Wire via three path arrays in ~/.pi/agent/settings.json (skills/prompts -> repo skills/+commands/, optional extensions -> adapters/pi/extension for the governance bridge tools). · python adapters/pi/launch.py and python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent pi --timeout 90 · Extension-bridged ask_user_question/dispatch_agent (tui/rpc interactive scope; headless fails fast with GOV_ASK_USER_HEADLESS); tool_calling and git_hooks native. Runtime E2E pending — capability honestly recorded as designed/degraded.

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

dsh 0.2+ (native derivation, FEAT-102): when the composed profile declares the host's agent-preset registry, the inserted row renders no directory. At boot it locates the host's own current standard declaration on the public loader tree, appends exactly two content deltas (the governance persona body and this package's two skill roots), and registers the result through the public agentPresets.register service. Host tool additions, renames and disabled flags therefore propagate on their own — upgrading dsh no longer invalidates the preset — and nothing is written under ${DSH_HOME}; uninstall only releases this package's own registration. The inserted row never renders a preset directory (DEC-366 ②): native registration is its only delivery face. Four unavailable states are each reported as one warning and write nothing — absent (no registry row in the composed tree: a directory-model host needs an explicit launch.py --install with DSH_HOME redirected to an isolated directory), disabled (the registry row is composed but disabled), unreadable (the loader entry tree could not be enumerated), and ambiguous (no unique mergeable base declaration: missing, duplicate, or an unsafe shape). 〔runtime: 2026-10-20, isolated DSH_HOME (redirected temp profile, real link: bundle, dsh 0.2.1-rc.2): roster shows 治理协调器, resolve reports no broken row, a session composes governance, the governance skill catalog contains software-project-governance + the command shims while a standard session does not, ${DSH_HOME}/.agent-presets stays absent; Windows-only, single-host evidence〕 The paragraphs below describe the explicit renderer (launch.py --install) that remains for operators and tests.

Restart the dsh web profile after installing — the bundle layer applies at profile boot (boot-time, not HMR). The explicit renderer (python adapters/dsh/launch.py --install, run with DSH_HOME redirected to an isolated directory) writes 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). The explicit renderer writes 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 (an explicit re-install recreates 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) — write_side_refusal: the real user root is refused with exit 2; only a redirected DSH_HOME (isolated env) is written
# upgrade: git pull, then restart dsh for native registration; the inserted row never re-renders a directory — a directory-model install is refreshed explicitly with `launch.py --install` under a redirected DSH_HOME (`--sync` is isolated-env only; the real user root is refused with exit 2)
python adapters/dsh/launch.py --uninstall        # uninstall — deletes exactly .agent-presets/governance/ (--dry-run to preview); same write-side guard: the real user root is refused with exit 2 (redirected DSH_HOME only)
# downgrade: git checkout v<old-tag> + --install under a redirected DSH_HOME (the real user root is refused with exit 2); the row never renders and an explicit re-install just 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: ge