dsh-completion-guard

简体中文

A task-contract and completion-certification plugin for DeepSeek Harness (DSH). It preserves requirements, prohibitions, acceptance criteria, later corrections, and bounded evidence so a task can be certified only when current successful evidence matches the current contract.

Quick start

Install the published plugin into a DSH Web profile:

dsh plugin --profile web add dsh-completion-guard@0.2.1

Restart DSH Web, open a session, and enable the guard:

/context-guard on
/context-guard status

Activation is opt-in by default. status reports whether the guard is enabled, the current epoch and contract revision, pending and passed item counts, the evidence count, and integrity state. off stops capture and gating for the session while preserving its prior history; clear supersedes every pending requirement/acceptance under a CLEAR: sentinel (prohibitions retained) so an empty-binding checkpoint can certify while the guard stays on; diagnose returns a bounded diagnostic view.

Activation modes

activation accepts two values:

Value	Behavior
opt-in	Default. A session remains unprotected until /context-guard on is recorded in that session.
always	Starts enabled before the session log is replayed. /context-guard off disables the guard for that session until a later /context-guard on.

To start Context Guard automatically for sessions in a DSH profile, add an ID-targeted override to that profile's cordis.patch.yml. For the default Web profile on macOS or Linux, this file is normally ~/.dsh/profiles/web/cordis.patch.yml:

- id: context-guard
  name: dsh-completion-guard
  config:
    activation: always

Restart that DSH profile after changing the configuration, then run /context-guard status in a session to confirm that the guard is enabled. Because always enables the guard before replay, applying it to a profile that already has persisted sessions can cause earlier user messages in those sessions to be captured when their logs are rebuilt. Use opt-in when protection should begin only after an explicit per-session command.

Once enabled, Context Guard captures direct user requirements and acceptance criteria. Tool results become citable evidence only after DSH persists them. Before the model claims the whole task is complete, it must call the injected context_guard_checkpoint tool with matching evidence IDs; an incomplete or stale binding cannot certify completion.

What it protects

• Captures requirement, acceptance, and prohibition clauses with stable identities and append-only supersession.
• Derives bounded, redacted evidence from persisted DSH tool calls and results.
• Requires method, operation, subject, surface, and outcome to match where the contract makes them explicit.
• Re-verifies certificates when a session is rebuilt or resumed and fails closed on integrity loss.
• Blocks Goal completion and whole-task completion claims while enabled unless a current certificate exists.

Status and compatibility

Version 0.2.1 is available from npm and the GitHub release.

The project was renamed from dsh-context-guard to dsh-completion-guard on 2026-08-29 to avoid a name collision with an unrelated DSH plugin (kpl0111/dsh-context-guard, tool-result pruning). The internal Cordis bundle id stays context-guard, and the previous npm package dsh-context-guard will be deprecated in favor of this package. It targets DSH 0.1.1-rc.2, Node.js >=22, and pnpm >=11.

The 0.2.1 release suite contains 138 tests (105 domain/core). It attributes shell evidence to the session cwd when the tool omits workdir, supports literal 2>&1 diagnostics and read-only inspection commands, maps process verbs to run evidence, and exposes actionable hints when a checkpoint binding is rejected. 0.2.1 adds a session-layer capture filter so clarification questions, meta comments, and bare progression phrases (继续, continue) never become contract items; de-duplicates repeated recovery notifications; adds /context-guard clear; and documents how a goal completes when the guard is disabled or blocked. A macOS live Web run loaded the published profile package and certified a real pnpm test result; Windows 0.2.1 native acceptance is still pending.

Context Guard recognizes only a small, auditable shell and PowerShell command subset. Unsupported or ambiguous syntax stays incomplete instead of being partially trusted. Compound commands, variables, non-whitelisted executables, file-target redirects, and in-place sed remain outside the certifiable surface. See docs/COMPATIBILITY.md for the exact grammar and platform evidence.

Boundaries

Context Guard certifies completion; DSH still owns Goal, Todo, Compaction, continuation, permissions, and tool execution. This plugin is not a security sandbox, semantic proof system, token-pruning tool, or replacement for those DSH facilities.

Evidence is bounded and redacted. Complete prompts, stdout, file contents, credentials, Authorization headers, URL query values, image bytes, and raw transcripts are not stored by the guard. See docs/PRIVACY.md.

Relationship to Codex Context Guard

This project ports deterministic behavior from GreenLv/codex-context-guard, with v0.8.8 as its semantic baseline. The two repositories serve different runtimes:

• codex-context-guard is the Codex Hook/Python implementation with Codex plugin-cache and Hook lifecycle integration.
• dsh-completion-guard is an independent TypeScript implementation over native DSH Session events, commands, tools, and agent lifecycle.

They do not share runtime state, installers, caches, or release histories. Fixes are contributed to the repository that owns the affected runtime and are ported deliberately when the same behavior belongs in both products. See docs/UPSTREAM_BASE.md and docs/PORTING_NOTES.md for the exact reused and replaced boundaries.

Documentation

• CHANGELOG.md — versioned user-visible changes.
• docs/ARCHITECTURE.md — ownership, durable state, and certification pipeline.
• docs/COMPATIBILITY.md — supported DSH versions and certifiable command subset.
• docs/LOCAL_ACCEPTANCE.md — deterministic, isolated, native, and public-package validation scopes.
• docs/distribution.md — verified public distribution destinations and the rename note.
• docs/PRIVACY.md — stored facts, prohibited data, and failure behavior.
• docs/UPSTREAM_BASE.md — semantic baseline and repository authority boundary.
• docs/PORTING_NOTES.md — behavior retained from Codex and DSH-specific replacements.

Development

pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test
pnpm run lint
pnpm run build
pnpm run pack:check

These commands validate the source and package candidate. CI, native-platform acceptance, npm publication, GitHub release identity, and runtime-profile installation remain separate evidence scopes.