dsh-doc-impact

Deterministic documentation-impact enforcement for DeepSeek Harness.

The plugin links code and documentation into a declarative impact graph. When an agent changes files during a turn, dsh-doc-impact diffs the workspace against the turn baseline, matches the delta against project rules, and — before the turn closes — steers the agent to review or update the affected documents. Implementing the plugin as a standard Cordis extension means no DSH core changes (SPEC §14, §93).

packages/auth/src/session.ts changed

→ docs/authentication.md
→ docs/security/session-lifecycle.md

Install

dsh plugin --profile web add link:/path/to/dsh-doc-impact   # local checkout
# or, once published:
dsh plugin --profile web add dsh-doc-impact

Then restart the harness so the plugin is loaded.

Workspace configuration

Create .dsh/doc-impact.yml in the project the agent works 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

  # Concise form is also accepted:
  - id: configuration-contract
    code: [packages/config/**]
    docs: [docs/configuration.md]
    direction: bidirectional
    relation: specification

Personal overrides belong in .dsh/doc-impact.local.yml (add it to .gitignore):

disabledRules:
  - legacy-docs

Plugin-level defaults (profile patch)

- insert:
    - id: doc-impact
      name: dsh-doc-impact
      config:
        enabled: true
        configFile: .dsh/doc-impact.yml
        defaults:
          mode: remind
        safety:
          maxReminderRounds: 2
          onLimit: allow        # allow | warn | error
        changeDetection:
          maxSnapshotFiles: 10000
        debug: false

How it works

1. Baseline — at the turn's first step the plugin records HEAD and the content hashes of every already-dirty file (git mode) or of all selector-matched files (filesystem fallback). Pre-existing user changes are therefore never attributed to the agent (SPEC §16-§19).
2. Stop check — on agent/turn-stopping the plugin diffs the workspace against the baseline (including commits the agent made mid-turn), matches the delta against the rules, and auto-resolves impacts whose targets were updated (SPEC §31, §88).
3. Steer — unresolved impacts produce one grouped reminder, and the agent gets another model step to update or review the documents.
4. Resolve — for strict modes the agent calls doc_impact_resolve { ruleId, status, reason? } with reviewed-current, updated (verified against the actual file delta), or not-applicable (non-empty reason required).
5. Loop protection — remind steers once per impact fingerprint; strict modes stop after maxReminderRounds and honor onLimit (fail-open by default, SPEC §34-§36).

Commands and tools

Interface	Purpose
/doc-impact	current pending/resolved status
/doc-impact check	recompute impacts now
/doc-impact explain <ruleId>	show one rule and whether it is triggered
/doc-impact changed	files the plugin attributes to this agent
doc_impact_resolve	explicit resolution tool (strict modes)
doc_impact_status	read-only status tool

Plugin Configuration UI

The plugin ships a browser half (lib/client.js, exports "./client"), so Settings → Plugins → Plugin Configuration shows a "Doc Impact" card bound to the doc-impact settings namespace. It follows the first-party card model:

• staged edits — nothing writes before Save; Discard drops drafts;
• the header carries an unsaved badge while drafts exist;
• Save stays disabled until there is something to write (and while a draft is invalid or a save is in flight);
• every field shows whether saving would leave a user-layer override and, when one stands, a per-field Reset that reverts to the composition layer.

Editable fields: enabled, configFile, default mode, maxReminderRounds, onLimit, maxSnapshotFiles, debug. The profile patch row's config: acts as the composition base under these user edits; the engine reads the merged view live (toggling enabled silences the plugin without a restart).

Development

npm install
npm run check   # typecheck + tests + build

The core (src/config, src/graph, src/changes, src/engine) is DSH-independent and testable without the harness; only src/dsh imports @deepseek-ai packages (SPEC §83, §92). Integration tests exercise real git repositories, including the Definition-of-Done scenario (SPEC §95).

Status

MVP scope per SPEC §80: code-to-docs / docs-to-code / bidirectional rules, glob include/exclude, git + filesystem baseline detectors, agent/turn-stopping continuation, reminder aggregation, remind + require-resolution (plus require-review / require-update modes), loop protection, commands, unit and integration tests.

License

MIT