Preface

In DSH’s plugin-based development, long-running task agents often encounter a practical issue: while the initial requirements are clear, the scope, constraints, or direction may subtly shift as execution progresses. Existing approaches typically have Plan Mode addressing “Is the plan correct?” before implementation, whereas dsh-requirements-alignment focuses on “Are we still solving the same problem?” during execution.

Maintained by jiezeng2004-design under the MIT license, the package.json version is 0.4.2. It requires Node.js >=22.18.0 and uses packageManager set to pnpm@11.19.0.

What is This

dsh-requirements-alignment is a DeepSeek Harness (DSH) plugin designed as a runtime requirement drift guard. It converts user requests into a maintainable requirement baseline and protects this baseline during agent execution.

It does not modify plan mode, exit_plan_mode, or any @deepseek-ai/* core packages.

Core Mechanism

Establishing the Requirement Baseline

The plugin establishes and maintains a requirement baseline with fields including:

  • goal
  • explicitConstraints
  • mustPreserve
  • allowedScope
  • userDecisions
  • openDirectionDecisions

The establish_baseline tool records the baseline. This operation does not prompt the user; repeated recordings increment the baseline revision.

Detecting Direction-Level Drift

In the default auto mode, the plugin injects the drift-guard strategy into each agent’s prompt at order 60. It focuses on direction-level changes, such as:

  • Scope expansion
  • Constraint conflicts
  • User-visible behavioral changes
  • Architectural changes
  • Assumption failures
  • Changes in user direction

Recording Drift and Querying the User

The report_drift tool records a drift candidate and queries the user once via the native user-questions channel, then records the user’s decision.

By default, it provides approve and stay-within-scope options. When the user selects an exact note, the result can map to approve, reject, or revise.

Only the alignment state managed by this plugin enters the requirement baseline; unrelated ask_user_question calls do not pollute this baseline.

Commands and Modes

/align

/align is used to check the current alignment state and trigger a new alignment inspection. It only performs a check and does not block execution.

/align-mode

/align-mode is used to view the mode snapshot and set a runtime override.

To persist a runtime override:

/align-mode auto
/align-mode manual
/align-mode off

To remove the runtime override:

/align-mode reset

The documentation also provides a session-specific switching method, which only affects the effective mode for the session calling the command:

/align-mode session

Four-Layer Mode Model

The plugin uses a four-layer mode model: session override, runtime override, profile default, and effective mode.

The effective mode takes the first valid value in the following order:

valid session override -> valid runtime override -> valid profile default -> auto

If a persisted mode value is invalid, the plugin falls back to the next valid layer or the profile default and may repair the settings document.

State Persistence

The canonical alignment state is persisted to an AlignmentStateStore sidecar, with the backend being the official storage-domain over storage-json. This state is not written to session events; the session log only receives official DSH events.

It supports resume, fork, and compaction recovery. Session overrides are keyed by session lifecycle identity, noted as id + createdAt + cwd in the documentation; forks inherit the effective session override at the seed boundary.

The alignment/* event vocabulary is used only for legacy compatibility, migration, and test/fold fallbacks; production never appends it.

Installation and Enabling

The installation commands in the documentation all include --profile web. The documentation also shows registry-based installation commands:

dsh plugin --profile web add dsh-requirements-alignment

For a local checkout, the documentation provides the following form:

dsh plugin --profile web add <path-to-this-checkout>

The plugin is installed as a profile bundle, including dsh.bundle.patch and cordis.patch.yml, and adds two entries:

  • requirements-alignment
  • requirements-alignment-ask-user

The web client injects:

  • @deepseek-ai/dsh-client-runtime
  • @deepseek-ai/dsh-client-locale

Typical Usage

  1. Install the plugin:
dsh plugin --profile web add dsh-requirements-alignment

  1. Start a normal DSH task. The auto mode is enabled by default; clear tasks run with zero interruptions, only querying the user when execution is about to change direction.

  2. Use /align at any time to check if the current execution still matches the requirement baseline.

  3. To change the running mode, use:

/align-mode auto
/align-mode manual
/align-mode off
  1. To remove the runtime override, use:
/align-mode reset

Use Cases and Considerations

It is suitable for DSH plugin workflows that need to maintain requirement direction consistency during long tasks. It can be used in combination with Plan Mode: Plan Mode focuses on pre-implementation plan review, while dsh-requirements-alignment focuses on in-implementation direction preservation.

Notes:

  • The plugin runs with the current dsh process permissions; check the source code and license before installation.
  • The plugin license is MIT.
  • The documentation only provides installation commands with --profile web, without specifying if this is required for all installations.
  • The documentation shows both registry-based and local checkout forms, without clearly recommending a single command.

Conclusion

The value of dsh-requirements-alignment lies in transforming “user intent” from a one-time prompt into a maintainable runtime baseline: recording direction, observing drift, querying once when necessary, and writing decisions back to the baseline.

GitHub repository:

https://github.com/jiezeng2004-design/dsh-requirements-alignment