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

1. 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.
2. 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.
3. Steer — unresolved impacts produce one grouped reminder and another model step in which the agent can review or update the affected documents.
4. Resolve — strict modes require doc_impact_resolve with reviewed-current, updated, or not-applicable; the last status requires a reason.
5. 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.