DSH Release Guardian

简体中文 · Architecture · Security model · Troubleshooting

Local, deterministic release-risk checks for Git changes. Use the same scanner through a DeepSeek Harness host tool, a standalone CLI, an optional Codex skill adapter, or an optional Claude Code plugin.

中文概览：Release Guardian 在本机读取 Git 变更，检查新增代码和变更文件中的发布风险，并发现常见项目检查。默认只读，不执行项目代码；只有用户明确授权后才会运行所展示的检查命令。

What v0.1 does

• Scans worktree, staged, or range Git changes.
• Applies deterministic rules to changed-file metadata and added lines.
• Discovers test, typecheck, and build commands for JavaScript, Python, Go, Rust, Java, and .NET projects.
• Produces a human-readable report or a versioned JSON report.
• Registers the release_guardian_check tool when installed as a DeepSeek Harness bundle.
• Gives Codex a safety-aware workflow through the optional release-guardian skill.
• Installs into Claude Code as a plugin: the release-guardian skill, a read-only release-auditor subagent, a dsh-release-guardian command on the session PATH, and an opt-in pre-commit gate.

Release Guardian is a risk signal, not a proof that a release is safe. A ready verdict means that this scan found no release-blocking condition within its configured scope.

Choose an entry point

All entry points use the same release-report contract and the same explicit authorization boundary for project checks.

These are adapters, not separate scanners. See Architecture for the component and trust-boundary map.

Safety model

The default check operation is read-only with respect to the target repository. It runs local Git commands and reads configuration and manifest files, but it does not execute project code. Release Guardian itself has zero telemetry and does not install project dependencies, publish packages, or deploy software.

Project checks are a separate, explicitly authorized operation:

• The CLI runs them only with --run-checks; it displays the exact plan and asks for confirmation. Non-interactive use also requires --yes.
• The host tool runs them only with action: "run" and exact command IDs from a prior discovery response.
• Approved commands are not sandboxed. They run with the invoking user's permissions in the repository.
• Discovery adds offline/no-restore/read-only flags where supported and execution uses a reduced environment, but these controls are best effort. They are not a network or filesystem security boundary.
• Execution is allowed only for a complete worktree scan with untracked files included. Approval IDs are bound to the canonical repository, effective baseline policy, and exact diff fingerprint; any source or configuration change invalidates prior approval.
• Configured commands may contain arbitrary argv. Merely placing a command in .release-guardian.yml discovers it; configuration is never an execution grant.

Review every displayed command before authorizing it.

Report security-boundary bypasses through the private process in SECURITY.md; never paste a real credential into a public issue.

Development setup and pull-request expectations are documented in CONTRIBUTING.md. Release notes are in CHANGELOG.md.

Requirements

• Node.js ^22.19.0 or >=24.0.0
• Git
• The relevant language toolchains only if checks will be executed
• For the DeepSeek Harness route: pnpm plus either dsh on PATH or the official npx @deepseek-ai/dsh launcher

The host bundle is tested against @deepseek-ai/dsh 0.1.0-rc.6. DeepSeek Harness is still a developer preview, so re-run the packed-profile smoke test when upgrading RC versions.

Compatibility

Install

Prebuilt GitHub release (recommended)

Download the prebuilt tarball from the latest GitHub release, then install it into a DSH profile:

curl -LO https://github.com/XiaoSong1223/dsh-release-guardian/releases/download/v0.1.0/dsh-release-guardian-0.1.0.tgz
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
  ./dsh-release-guardian-0.1.0.tgz
npx @deepseek-ai/dsh@0.1.0-rc.6 --profile headless --dump-config

The release tarball contains built JavaScript and does not require permission to execute a package build during installation.

Install directly from GitHub

DSH also accepts a pinned GitHub source:

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
  github:XiaoSong1223/dsh-release-guardian#v0.1.0

Git installs run this TypeScript package's prepare build. pnpm 10 and newer require the profile to explicitly allow that build. Review the pinned source, add dsh-release-guardian: true under allowBuilds in the profile's pnpm-workspace.yaml, and repeat the command. Prefer the prebuilt release tarball when you do not want to grant install-time build permission.

Build from a checkout

From this checkout, install Release Guardian's own dependencies and build a package tarball:

npm ci
npm pack

npm pack runs the package prepare script, so the resulting dsh-release-guardian-0.1.0.tgz contains built JavaScript.

Standalone CLI

Install the built tarball globally:

npm install --global ./dsh-release-guardian-0.1.0.tgz
dsh-release-guardian --help

For development without a global install, build and invoke node lib/cli.js from this checkout.

DeepSeek Harness bundle

Add the same built tarball to the desired DSH profile:

dsh plugin --profile headless add ./dsh-release-guardian-0.1.0.tgz

# No global dsh installation is required:
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
  ./dsh-release-guardian-0.1.0.tgz

Replace headless with the profile you use. dsh plugin initializes a missing profile, forwards add to pnpm in that profile, and activates this package's cordis.patch.yml bundle. Boot the profile normally; it exposes the release_guardian_check host tool. This package does not provide a Web UI.

Optional Codex adapter

This repository is also a Codex plugin bundle. Install or load the repository through Codex's plugin controls, then ask Codex to use the release-guardian skill for a release audit. The skill calls its self-contained runner at:

skills/release-guardian/scripts/release-guardian.mjs

The runner makes the adapter work from the installed plugin without requiring a global CLI. If the companion script is unavailable, the adapter may fall back to dsh-release-guardian on PATH, which is useful for development and older package layouts.

If you copy the skill manually instead of installing the plugin bundle, copy the entire skills/release-guardian/ directory, including scripts/release-guardian.mjs. Copying only SKILL.md removes the bundled runner; in that case the adapter works only when a compatible dsh-release-guardian is already on PATH.

Why does a DSH package contain .codex-plugin/plugin.json? It is distribution metadata for the optional Codex adapter: it tells Codex where the packaged skills and presentation assets live. It does not change DSH loading, register the DSH host tool, execute code at install time, or make Codex a runtime dependency of the scanner. Keeping this manifest in the same release artifact lets the DSH bundle, CLI, and Codex skill share one reviewed implementation and version.

See Troubleshooting if Codex cannot find the skill or runner.

Optional Claude Code plugin

This repository is also a Claude Code plugin and a single-plugin marketplace. Add the marketplace, then install the plugin:

/plugin marketplace add XiaoSong1223/dsh-release-guardian
/plugin install dsh-release-guardian@release-guardian

A local checkout works the same way and is the recommended way to try changes:

npm ci && npm run build

/plugin marketplace add /absolute/path/to/dsh-release-guardian
/plugin install dsh-release-guardian@release-guardian

The plugin adds four surfaces:

Claude Code never builds this package, so the launcher resolves a runnable CLI in this order: the DSH_RELEASE_GUARDIAN_CLI environment variable or the plugin's cli_path option, then the self-contained skills/release-guardian/scripts/release-guardian.mjs, then lib/cli.js, then a dsh-release-guardian already on PATH. The bundled runner comes before lib/cli.js because it needs no installed dependencies, and a plugin source without a lockfile never gets them. If nothing resolves, the launcher exits 69 and prints what to build or install; it never installs anything itself.

The pre-commit gate is off by default. Enable it per user or project with the plugin's commit_gate option, or by exporting DSH_RELEASE_GUARDIAN_COMMIT_GATE=1. It scans staged changes, or the worktree for git commit -a, and reports only rule IDs and paths, never finding text. It is advisory, not a security boundary: a missing CLI, a timeout, or an unreadable report allows the commit and says the gate did not run.

The plugin deliberately ships no allowed-tools pre-approval for the skill. A Bash(dsh-release-guardian check:*) rule would also pre-approve --run-checks, which would defeat the execution gate, so each command follows the session's normal permission flow.

CLI

dsh-release-guardian check [options]
dsh-release-guardian rules
dsh-release-guardian explain RULE_ID

With no command, the CLI defaults to check.

Common examples:

# Unstaged, staged, and optionally untracked work against HEAD
dsh-release-guardian check --repo /absolute/path/to/repo

# Index changes against HEAD
dsh-release-guardian check --repo /absolute/path/to/repo --mode staged

# Changes from the merge base of origin/main and HEAD through HEAD
dsh-release-guardian check --repo /absolute/path/to/repo --base origin/main --head HEAD

# Stable machine-readable report
dsh-release-guardian check --repo /absolute/path/to/repo --format json

# Discover and then explicitly approve the displayed test/typecheck plan
dsh-release-guardian check --repo /absolute/path/to/repo \
  --checks test,typecheck --run-checks

# After a static JSON scan, execute only one previously displayed check ID
dsh-release-guardian check --repo /absolute/path/to/repo \
  --checks test --check-id sha256:... --run-checks

# Rule inventory and remediation details
dsh-release-guardian rules
dsh-release-guardian explain RG103

Check options

range mode requires --base. --base conflicts with an explicitly selected non-range mode.

Verdicts and exit codes

The rules and successful explain commands exit 0.

Diff modes

• worktree compares the working tree with HEAD; untracked files are included by default.
• staged scans index changes against HEAD; untracked files are not part of this mode.
• range computes merge-base(BASE, HEAD_REF) and scans through HEAD_REF. Range and staged scans are read-only review scopes; project checks execute only in full worktree mode.

Diffs are collected with external diff drivers and text conversion disabled. Limits fail closed: truncation produces RG405 and an inconclusive verdict.

Rules

Rules inspect only the selected change: changed-file metadata plus added lines, except where a rule explicitly concerns deletion, binary content, or truncation. Evidence for recognized secrets is redacted in reports.

Run dsh-release-guardian explain RULE_ID for the remediation attached to a rule.

Check discovery

Discovery reads manifests without running them. In Git repositories it considers only tracked files and untracked files not ignored by Git, then applies intrinsic exclusions for virtual environments, dependency trees, build output, and nested agent worktrees. It looks to the configured manifest depth (default 4), prefers configured commands, de-duplicates equivalent plans, and returns at most 256 checks by default. The report includes candidate, returned, limit, truncation, and completeness counts.

Discovery does not verify that a tool or dependency is installed. Availability is determined only if the user authorizes execution.

.release-guardian.yml

The configuration is strict: version must be 1, and unknown fields are rejected. The implemented top-level keys are only version, diff, checks, and limits.

version: 1

diff:
  include_untracked: true
  max_bytes: 10485760
  exclude:
    - "**/.claude/worktrees/**"
    - "**/.codex/worktrees/**"
    - "**/.venv/**"
    - "**/vendor/**"
    - "**/dist/**"
    - "**/node_modules/**"
    - "**/*.min.js"
  generated:
    - "**/*.generated.*"

checks:
  required: [test, typecheck]
  discover:
    max_depth: 4
  commands:
    - id: project-test
      category: test
      cwd: .
      argv: [npm, --offline, run, test]
      required: true

limits:
  max_files: 5000
  max_findings: 500
  max_check_output_bytes: 65536
  max_checks: 256

Implemented camelCase/snake_case aliases are:

checks.required accepts only test, typecheck, and build. Each checks.commands entry accepts only:

• id: stable identifier containing letters, digits, ., _, or - (maximum 64 characters)
• category: test, typecheck, or build
• cwd: non-empty repository-relative directory
• argv: non-empty array of non-empty strings; it is never interpreted as a shell command
• required: optional boolean, default true
• timeoutSeconds: optional positive integer

timeoutSeconds overrides the invocation/host-wide timeout for that configured command.

Configured commands are only added to the displayed plan. They still require the same explicit execution authorization as discovered commands.

Project policy is loaded from the trusted baseline commit (HEAD for worktree/staged scans and the merge base for range scans). A policy file introduced or modified by the audited change does not take effect for that same scan and makes the result incomplete. diff.exclude and diff.generated reduce non-blocking noise, but they never suppress credential rules or a rule whose adjudicated disposition is block.

JSON report contract

--format json and the host tool emit the same snake_case report with schema_version: "1". It includes the verdict, repository and diff metadata, summary counts, changed files, contextual findings, check plans/results, diagnostics, warnings, and duration. Additive coverage fields include:

• diff.files_changed, files_seen, files_excluded, and files_unseen, which reconcile the selected Git scope;
• diff.exclusions, which lists the effective pattern, count, and bounded path samples;
• diff.fingerprint and candidate_lines_scanned, which make authorization and scan scope auditable;
• check_discovery, which reports completeness, candidates, returned checks, limit, truncation, its current_worktree source, and whether that source matches the selected diff scope;
• each file's separate change_status and content_kind, so binary or uninspected content does not hide whether a path was added, modified, deleted, renamed, or untracked;
• each finding's context, rationale, and occurrences.

Consumers should require the expected schema_version, tolerate additive fields, and use names rather than field order. Fields documented for schema version 1 are the v0.1 machine-readable contract; an incompatible report-format change requires a new schema_version.

Host tool flow

Call release_guardian_check with an absolute repo_path. The request schema version is also "1".

1. Call with action: "discover" (or omit action) to scan and receive the JSON report and check plan.
2. Show the verdict, findings, and each check's exact id, cwd, and argv to the user.
3. Only after explicit authorization, call with action: "run" and the exact approved_command_ids from that discovery response. Use the same repository in worktree mode with untracked files included and without intervening source/configuration changes.

Supported host inputs are schema_version, repo_path, config_path, mode, base, head, include_untracked, max_diff_bytes, categories, action, and approved_command_ids.

Documentation

• Architecture: shared core, entry-point adapters, data flow, and packaging.
• JSON output schema: schema version 1 fields and consumer guidance.
• Security model: execution boundary, authorization binding, and residual risk.
• Troubleshooting: installation, DSH, Codex, scanning, and execution failures.
• Testing and verification: local gates, coverage areas, and the packed-profile smoke test.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run check
npm run guardian:self

npm run check runs typechecking, a production/Codex-runner build, tests, package verification, publint, and the pack check. npm run guardian:self expects built output and scans this checkout without executing its discovered checks.

License

MIT