dsh-doc-impact
Deterministic documentation-impact enforcement for DeepSeek Harness.
dsh-doc-impact links code and documentation through a declarative impact graph. When an agent changes files, the plugin compares the workspace with the turn baseline and steers the agent to review or update every affected document before the turn closes.
Specification
Installation
Install the published npm package by name:
dsh plugin --profile web add @yadsh/dsh-doc-impact
To remove the plugin:
dsh plugin --profile web remove @yadsh/dsh-doc-impact
Restart the DeepSeek Harness host if bundle hot reload does not pick up the newly installed plugin or browser client.
How it works
packages/auth/src/session.ts changed
→ docs/authentication.md
→ docs/security/session-lifecycle.md
- Baseline — on the first step of a turn, the plugin records
HEAD and the content hashes of already-dirty files. Pre-existing user changes are never attributed to the agent.
- Stop check — on
agent/turn-stopping, it compares the workspace with that baseline, including commits made during the turn, and matches the delta against project rules.
- Steer — unresolved impacts produce one grouped reminder and another model step in which the agent can review or update the affected documents.
- Resolve — strict modes require
doc_impact_resolve with reviewed-current, updated, or not-applicable; the last status requires a reason.
- Loop protection — reminders are fingerprinted and bounded by
maxReminderRounds, with configurable fail-open or fail-closed behavior.
Configuration
Create .dsh/doc-impact.yml in the workspace the agent operates on:
version: 1
defaults:
mode: remind # remind | require-review | require-resolution | require-update
scope: turn # turn | session
changeDetection: auto # auto | git | filesystem
rules:
- id: auth-docs
description: Authentication behavior documentation
code:
include:
- packages/auth/**
- packages/server/src/auth/**
exclude:
- "**/*.test.ts"
docs:
- docs/authentication.md
direction: code-to-docs # code-to-docs | docs-to-code | bidirectional
relation: documents # documents | specification | synchronized | related
mode: require-resolution
- id: configuration-contract
code: [packages/config/**]
docs: [docs/configuration.md]
direction: bidirectional
relation: specification
Personal overrides belong in .dsh/doc-impact.local.yml, which should be ignored by Git:
disabledRules:
- legacy-docs
The bundle inserts the dsh-doc-impact Cordis row. Override its defaults in the profile patch when needed:
- id: dsh-doc-impact
config:
enabled: true
configFile: .dsh/doc-impact.yml
# Detect impacts without steering reminders into the turn: tools,
# `/doc-impact`, and status keep working, reminder rounds are not spent,
# and the limit notice is not sent. Useful with the default `true`.
steer: true
defaults:
mode: remind
safety:
maxReminderRounds: 2
onLimit: allow # allow | warn | error
changeDetection:
maxSnapshotFiles: 10000
# Wording of the two steering messages; empty = built-in text.
# reminderTemplate placeholders: {intro} {count} {body} {tail} — {body}
# carries the generated impact list and is required.
# limitTemplate placeholders: {rounds} {impacts} — {impacts} is required.
reminderTemplate: ""
limitTemplate: ""
debug: false
Commands and tools
| Interface | Purpose |
|---|
/doc-impact | Show pending and resolved impacts |
/doc-impact check | Recompute impacts immediately |
/doc-impact explain <ruleId> | Explain a rule and whether it was triggered |
/doc-impact changed | List files attributed to the current agent turn |
doc_impact_resolve | Resolve an impact explicitly in strict modes |
doc_impact_status | Read the current impact status |
Settings UI
The browser half adds the Doc Impact settings card to the Plugins page: the row this bundle occupies there carries a configure control that opens it. It provides staged edits, Save and Discard actions, an unsaved-state badge, validation, and per-field reset to composition defaults. The values stay in the dsh-doc-impact settings namespace, where they have always lived, so a configuration saved by an older build is read back by this one.
Editable fields include enabled, steer (send reminder messages, or detect silently), configFile, default mode, maxReminderRounds, onLimit, the reminderTemplate and limitTemplate message texts with their placeholders documented inline, maxSnapshotFiles, and debug. A template that loses its required {body} / {impacts} placeholder is rejected by the form, and the host falls back to the built-in wording. Saved settings apply to the merged runtime configuration without a host restart.
Diagnostics
Runtime events land in <$DSH_HOME>/logs/dsh-doc-impact/<YYYY-MM-DD>.log and mirror to the host console at warn and above. Every line's [dsh-doc-impact] tag is added by the logging pipeline itself, so the message text never repeats the plugin name — only unscoped host-console messages (activation, settings bootstrap) name it themselves. Without debug, the log already records every decision:
reminder sent: N impact(s), rules: … — a grouped reminder was steered into the agent turn, with the triggering rules and the attribution;auto-resolved impact for rule …: target updated — the agent already updated the target documentation, so no reminder is needed;reminder limit reached for rule …; allowing stop (onLimit: allow) — maxReminderRounds is exhausted and the turn is allowed to close;attribution probe failed / stop check failed; failing open — degraded runs; the agent loop is never blocked.
With debug: true (settings card or profile patch) the log additionally records baseline capture and every stop check with changed and pending counts.
What works now
- code-to-docs, docs-to-code, and bidirectional rules;
- include and exclude globs;
- Git and filesystem baseline detectors;
- reminder aggregation and
agent/turn-stopping continuation;
remind, require-review, require-resolution, and require-update modes;- explicit resolution tools, commands, and loop protection;
- unit and integration coverage, including real Git repositories.
Requirements
- Node.js 20 or newer
- pnpm 10.4.1 for development
- DeepSeek Harness
>=0.1.7-rc.2 <0.2.0
- Cordis
^4.0.1
Development
From the monorepo root:
pnpm install --frozen-lockfile
pnpm --filter @yadsh/dsh-doc-impact check
The core under src/config, src/graph, src/changes, and src/engine is DSH-independent. Only src/dsh imports @deepseek-ai packages.
The browser client source lives at src/client.ts. The build compiles it with
tsdown into the ignored package artifact lib/client.js; edit the source file,
never lib/ directly.
Releases
This package uses independent Nx Version Plans from the monorepo. Add a plan with pnpm release:plan; maintainers publish verified tarballs through the shared release workflow.
Contributing
Issues and focused pull requests are welcome. Read the monorepo contribution guide and run the package check before submitting a change.
License
MIT. This is an independent community project and is not affiliated with or endorsed by DeepSeek.
