dsh-information-environment-governance

---

doc_type: readme project: information-environment-governance version: 0.5.0 plugin_version: 0.11.0 status: active owner: maintainers last_reviewed: 2026-10-03 revision: 0.11.0-batch-6 verified_against: dsh-v0.2.1-alpha.1 language: en format_note: conservative-machine-readable-markdown

Information Environment Governance (IEG)

IEG is an additive project-governance layer for DeepSeek Harness. It governs the information environment an agent works in. The canonical definition of that term, the full positioning, and the authoritative scope live in PRODUCT-SPEC.md §1; this README links there rather than restating them.

Status: prototype, not production-ready. The package is dsh-information-environment-governance 0.9.1 — publishable and verified, but not published — and the publish target is undecided. Behavioural improvement (Gate C) and information integrity (Gate D) have no valid measurement for the current prompt revision, and packaging (Gate I) is partial. It is not recommended for a working profile. Current numbers are in MAINTENANCE-HANDOFF.md §3–§4; see Status.

At a glance

What is it? Information Environment Governance for DSH coding agents: one additive prompt section plus deterministic runtime gates, shipped as the dsh-information-environment-governance plugin. It is not a replacement system prompt, a second agent identity, a generic prompt improver, or a general safety layer.

What does it govern?

• project constraints;
• information / document lifecycle and integrity;
• workspace hygiene, where it directly supports the information environment.

What does it not govern?

• general AI safety / security;
• sandboxing;
• authorization;
• user-attention optimization.

Who is it for? Users who rely on coding agents for professional work without necessarily having a full software-engineering background.

The product message

The goal is not to make the agent "more intelligent"; it is to keep the project environment clearer, more consistent, and easier for the agent and user to understand over time.

This is an intended benefit, not a guarantee of reliability or of superior model capability. The practical problem is a project quietly turning into something neither the agent nor the user can reason about any more — the "unmaintainable pile" that starts as a few convenient files. Even when the user's understanding of the project direction becomes unclear, a well-maintained project environment gives the agent a cleaner basis for reconstructing project context.

中文说明

信息环境治理（Information Environment Governance，简称 IEG） 是为 DeepSeek Harness 上的编码智能体提供的一层 附加治理。它治理的是智能体所处的信息环境（Information Environment）： 智能体在项目中持续接触、依赖、修改或继承的持久化信息与项目约束。

治理什么

• 项目约束：目标、范围、术语、约束、当前阶段；
• 信息与文档的生命周期与完整性：存在性、状态、权威性、来源、替代关系、可检索性；
• 工作区整洁（workspace hygiene）——仅限直接支撑信息环境的部分。

不治理什么

• 通用的 AI 安全 / 安全防护；
• 沙箱（sandboxing）；
• 授权（authorization）；
• 用户注意力优化（user-attention optimization）。

面向谁：把编码智能体用于专业工作的用户，不要求具备完整的软件工程背景。

核心信息：目标不是让智能体“更聪明”，而是让项目环境随时间保持更清晰、更一致， 更容易被智能体和用户理解。这是期望收益，不是可靠性保证。

即使项目方向的把握变得模糊，一个维护良好的项目环境也能为智能体重建项目上下文 提供更干净的基础。

本项目的工作语言与权威文档为英文，本节仅为面向中文读者的简要说明；术语与产品边界 以英文文档为准（PRODUCT-SPEC.md §1）。

Contents

This repository is the project documentation and the working prototype of the plugin.

Document	Audience	Purpose
PRODUCT-SPEC.md	humans + agents	positioning, the canonical definition and scope, the two governance entry points, goals, requirements, success criteria — the single source of truth for what IEG is
ARCHITECTURE-SPEC-AGENT-REFERENCE.md	implementation agents	architecture, module contracts, diagrams, runtime integration, compatibility model. Part A is the source-verified host integration, its deltas, and residual assumptions. Part B is the target design, the acceptance matrix (§32), and the phase plan
MAINTENANCE-HANDOFF.md	maintainers	the maintained status record: current status and numbers (§3–§4, the single source of truth), blockers, backlog, process gotchas, workspace layout, and the naming/withdrawal history
TESTING.md	volunteers	the volunteer procedure: install, first trial, the A/B check, and deviation reporting
SECURITY.md	everyone	what IEG is not, the accepted limits (single source of truth), the out-of-scope list, and how to report a vulnerability
CONTRIBUTING.md	contributors	prerequisites, the checks to run (single source of truth), and the project rules
IMPLEMENTATION-VALIDATION-HANDOFF.md	agents	retired — a pointer to the §32 gates and the historical build order
docs/DOCUMENTATION-INDEX.md	everyone	the document inventory and the single-source-of-truth map
.github/ISSUE_TEMPLATE/	users + maintainers	the bug-report and feature-request forms a deviation report uses
repository root (package.json, cordis.patch.yml, src/, lib/, bin/ieg)	implementation agents	the working dsh-information-environment-governance package: manifest, kernel, three modules, the dsh-ieg terminal interface, and the verification chain. The root is the package — there is no plugin/ subdirectory
eval/	evaluation agents	behavioural and end-to-end evaluation: the harness, the seeded scenarios, and the sandbox runs

What IEG governs

IEG has two governance entry points:

1. Project Constraint Governance — keeps the project's objective, scope, terminology, constraints, and current phase explicit, and distinguishes declared understanding from actual behavioral consistency.
2. Information / Document Governance — keeps the state of project information explicit (existence, status, authority, provenance, supersession, retrieval eligibility) and governs the documents that carry it. Workspace hygiene is an enforcement mechanism inside this entry point, not a separate system.

Three primary areas are in scope:

1. Project Constraints — objective, scope, terminology, constraints, current phase.
2. Information State — authority, validity, provenance, supersession, lifecycle status.
3. Persistent Workspace — documents, artifacts, source/configuration, and generated files.

Explicitly out of scope

The following are not IEG's concern, and no future feature may drift into them:

• general AI safety or security;
• sandboxing;
• authorization;
• user-attention optimization (RETIRED — the capability was withdrawn in 0.7.0; see the history in MAINTENANCE-HANDOFF.md §13.2);
• unrelated agent behavior management.

Any future feature must show a direct connection to Information Environment Governance. The authoritative statement of this boundary is PRODUCT-SPEC.md §1 and §4; the security consequences are in SECURITY.md.

Modules (3, all enabled by default)

Module	Failure class	Concern
project-governance	FC-2.1	project orientation, scope, terminology, and constraint drift
information-integrity	FC-2.3	reuse of known-invalid or superseded information
workspace-governance	FC-2.2	unauthorized persistent workspace mutation

The former user-attention module and failure class FC-2.4 were removed in 0.7.0 and are classified "Out of Scope / Externally Solved". They are not a current capability; the withdrawal is recorded as history in MAINTENANCE-HANDOFF.md and ARCHITECTURE-SPEC-AGENT-REFERENCE.md Part B.

Interface: the dsh-ieg terminal command

The supported interface is a terminal command, dsh-ieg, run from a Debian shell. Running it with no arguments opens an ANSI numbered menu; every command also works non-interactively with flags, because CI and scripts call it. The entry file is bin/ieg.

dsh-ieg                      # usage (there is no interactive menu)
dsh-ieg prompt               # print the effective prompt, its version and byte count
dsh-ieg prompt edit          # $EDITOR on a temp copy of the effective text; validate; store
dsh-ieg --help / --version

There is no installation, update, uninstall or lifecycle surface here: a plugin cannot install itself, so §Install carries the only two official entry paths. Batch 5 removed the former install/update/uninstall commands, the start/pause/restart/exit control plane and the interactive menu, so prompt management is the whole interface — use enabled: false in the row config to turn governance off for a profile.

The prompt text lives in prompt.md, at $IEG_PROMPT_FILE, else /ieg/prompt.md where `` is $XDG_STATE_HOME else ~/.local/state. Every candidate is validated through the same kernel the plugin uses for a config-supplied override (no {{ }}, byte ceiling unless allowOverBudget; a refusal keeps the previous text and prints its reasons), and it is re-resolved on each assembly, so an edit applies without a remount. Precedence is the operator prompt.md > config prompt.file (when prompt.mode: replace) > prompt.append > the compiled default.

The plugin contributes one additive prompt section, ieg:governance (order: 8500, interpolate: false, complete never set) and two model-facing tools — record_orientation, read-only ieg_status, and read-only maintain_environment. At PROMPT_VERSION 0.5.0 the compiled section is 2,806 bytes against a 2,945-byte ceiling. It reports its own state through the ieg:status runtime-context line and the ieg.* diagnostic codes. Full runtime detail is in ARCHITECTURE-SPEC-AGENT-REFERENCE.md Part B.

Maintenance round

IEG also maintains the environment rather than only gating actions. One manually triggerable round, maintain_environment, inventories the workspace's persistent artifacts (authoritative specifications, implementation documentation, configuration, working notes, generated, historical, temporary and unknown), diagnoses duplication, obsolescence and declared drift, and returns proposed actions from a fixed vocabulary — KEEP | MERGE | UPDATE | REPLACE | DEPRECATE | REMOVE | LEAVE_UNCHANGED | REQUIRES_REVIEW — each with a reason and a confidence.

It proposes; it never applies. The tool is read-only by construction, and every destructive proposal needs an explicit human decision. Point it at a specific change with changed and it also reconciles: which other artifacts mention that subject, which of their stated facts have gone stale, and what it could not settle.

The runtime counts direct user instruction batches using the host's own turn accounting; internal steps, tool calls and generated context are excluded by construction. At seven it marks maintenance due in the runtime context and the round resets the counter.

What is not implemented is stated in MAINTENANCE-HANDOFF.md §3 — notably cross-document contradiction detection beyond declared state, which is listed as a future capability rather than a claim.

Install

IEG is a DSH plugin. It is installed by the host's own plugin installer and only afterwards managed by dsh-ieg. Those are two separate steps: dsh-ieg is supplied by the package itself, so it cannot bootstrap the package. On a clean machine a bare dsh-ieg is simply not on your PATH:

$ dsh-ieg prompt
bash: dsh-ieg: command not found

Install into a throwaway profile, never into a profile you rely on.

1. Standard install — DSH-native (recommended)

DSH installs a plugin from a registry package name, an absolute path, a git address, or a tarball. That is the first-install path:

# from the repository (the repository root IS the package)
dsh plugin --profile  add \
  https://github.com/ccneedb/dsh-information-environment-governance

# confirm the bundle row composed
dsh --profile  --dump-config | grep -A3 'id: ieg'

The DSH Web UI's plugin installation offers the same repository-URL path through its "Git repository" field — the graphical form of the same mechanism.

2. npm package

The package is publishable and verified, not yet published. The registry name dsh-information-environment-governance is currently unclaimed, so a first publication is a maintainer action, still withheld pending Gates C and D and the publish-target decision (Status). Until then, npm install from the registry does not resolve; build and install the exact artifact locally:

npm pack                        # builds exactly what npm would publish
dsh plugin --profile  add \
  "file:./dsh-information-environment-governance-.tgz"

The packed artifact carries exactly the runtime — lib/**, bin/ieg, cordis.patch.yml, package.json, README.md, LICENSE, CHANGELOG.md — and none of src/, test/, eval/, docs/. Package-level configuration detail is in docs/PACKAGE-REFERENCE.md.

3. Development and recovery

For working on IEG itself, or recovering a profile:

dsh plugin --profile  add "file:/path/to/this/repository"   # a checkout
dsh plugin --profile  remove dsh-information-environment-governance

A release tarball is attached to the GitHub release; it is a developer/recovery source, not the normal user path.

The dsh-ieg prompt CLI

dsh-ieg manages the prompt of an already installed IEG — nothing else. pnpm installs it into the profile beside the package rather than onto your PATH, so the dependable invocation is the profile-local binary:

/profiles//node_modules/.bin/dsh-ieg prompt

For a stable command, install the package globally with npm (npm install -g dsh-information-environment-governance, once published) or call it through npx dsh-ieg …. It has two commands: prompt (view the effective text, its version and byte count) and prompt edit (validate an edited copy and store it). It never installs anything.

Upgrading

A normal upgrade re-runs the host's own install for the profile; that is what re-resolves and re-links the package, and dsh-ieg is not involved:

dsh plugin --profile  add 
dsh --profile  --dump-config | grep -A3 'id: ieg'      # still composes
/profiles//node_modules/.bin/dsh-ieg prompt  # the effective text

First install, upgrade and developer/recovery all use the same DSH-native command; only the source changes (repository URL, registry name, checkout, or tarball).

Two caveats worth knowing before first use:

• a profile links the plugin at install time, so re-install after any source change or you will exercise the old code;
• IEG defaults to workspace.policy: ask and overlapCheck: ask, which fail closed in a composition with no approval channel. In a headless or agent-delegated session there is no one to answer, so the gate denies writes — see [MAINTENANCE-HANDOFF.md](M