dsh-requirements-alignment

一句话定位

防止 DeepSeek Harness 长任务执行方向漂移的插件：把用户最初的需求固化成一个"基线"，任务执行过程中除非真的改变方向，否则不打断用户。

核心能力

• 静默建立需求基线：把目标、显式约束、必须保留的行为、允许的范围、已确定的用户决策固化为可追溯的基线
• 仅在方向变更时打断用户：检测到范围扩张、约束冲突、用户可见行为变更、架构调整、数据模型变更、兼容性破坏、假设失效或用户方向变更时才发起一次确认
• 三种运行模式：Auto（默认，策略+工具+命令全开）、Manual（仅工具+命令）、Off（仅保留 /align-mode 命令），可运行时热切换
• 提供 /align 命令随时查看当前基线状态、漂移次数、最近一次决策
• 提供 /align-mode 命令切换模式并在 DSH Settings 中持久化用户覆盖
• 基线状态独立存放在 storage-domain 边车，会话恢复、fork、压缩后保持一致

技术实现

• 语言: TypeScript（ESM，构建输出到 lib/）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-storage-domain、@deepseek-ai/schemastery、zod
• 架构模式: 作为 Cordis profile bundle 注入（cordis.patch.yml 声明两个 row），通过 effect disposer 管理热插拔；canonical 状态写入 storage-domain 边车而非 session 事件
• 入口文件: src/index.ts（RequirementsAlignmentController，挂载策略段、两个工具、三个命令），辅助模块 policy.ts / mode-store.ts / runtime-mode-controller.ts / alignment-state-store.ts

适用场景

长任务、多步骤重构或跨多文件改动时，担心 AI 默默改了不该改的东西（比如破坏公开 API、改动 UI、引入新依赖）但又不想每个细节都审批。该插件让你只在 AI 真的要改变方向时才介入确认。短任务或纯修 typo 的场景下插件保持完全静默。

前置依赖与兼容性

安装方式

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

配置项

说明：模式实际生效值由三层决定——持久化的运行时覆盖（保存在 settings.yaml）→ Profile 默认（cordis.patch.yml 里的 mode）→ auto。可通过 /align-mode auto|manual|off|reset 热切换。

常见问题

Q: 这个插件和 DSH 自带的 Plan Mode 有什么区别？

A: Plan Mode 在执行前审查"方案是否合理"；Requirements Alignment 在执行过程中监督"是否还在做正确的事"。两者可以叠加：先 plan、approve，再让插件防止执行偏离已批准的方向。

Q: 安装后会自动打断我吗？

A: 不会。Auto 模式下插件默认静默监控，仅在执行即将改变任务方向（如范围扩大、约束冲突、架构变化、用户临时改方向）时才向你发起一次确认。

Q: 任务的"基线"存放在哪里？

A: 存放在 DSH 官方的 storage-domain 边车（AlignmentStateStore，单元名 requirements_alignment，后端 storage-json）。会话事件流里不再写入 alignment/* 类型事件，因此即便卸载插件或裸 DSH 也能正常读取该会话。

Q: 如何切换 Auto / Manual / Off？

A: 在 DSH 中运行 /align-mode auto（或 manual / off）即可热切换，无需重启 profile；/align-mode reset 恢复到 profile 默认值；/align-mode 不带参数会打印三层快照。

Q: 子代理可以问用户吗？

A: 不可以。DSH 子代理不允许向用户提问（会收到 DELEGATED_CALLER 错误）。子代理如果需要变更基线，会把"需求漂移候选"块写入最终报告交给父代理，由父代理执行漂移协议。

Q: 卸载插件会丢失基线数据吗？

A: 不会。canonical 状态独立存放在边车中，卸载只移除工具、命令和策略段，不会删除已建立的基线、漂移记录或用户决策。

Q: 什么情况下不该用这个插件？

A: 短任务、纯 typo 修正、明确的小范围 bugfix 可以不用——插件对此类任务完全静默；但前提是你信任 agent 在范围扩大时主动触发漂移协议。

上手难度

进阶 — 插件本身无配置门槛（默认 Auto 模式即可工作），但要理解"基线"概念和 drift 分类需要先读一遍策略说明，且 /align-mode 的三层模式模型（profile 默认 / 运行时覆盖 / 有效值）需要适应。

已知问题与限制

• 软引导而非硬阻断：漂移检测由模型判断，插件只记录和重新对齐，不会阻止执行；理论上模型可能漏报方向变更
• 自然漂移检测率并非 100%：在没有显式协议指令的自然任务中，中途用户方向变更触发 report_drift 的实测命中率约 3/4（README 自述）
• /align 需要命令适配器：无 UI 的 spine（如 headless profile、ACP 自动化）不派发 slash 命令
• 侧车只增不减：每次基线、漂移、决策、人工检查都会追加一个全状态 checkpoint，没有剪枝机制，超长会话会持续累积
• 没有 Web 状态卡片：对齐状态目前只能通过 /align 文本或会话级策略摘要查看，缺少原生 Web 设置面板
• 不支持会话级模式：/align-mode 改变的是共享的 profile/运行时覆盖，不是单个会话的设置；会话级模式选择器计划在 v0.4.0 提供（详见 docs/ROADMAP.md）
• 子代理不能问用户：见 FAQ

Runtime requirement drift guard for DeepSeek Harness.

Keep long-running agents aligned with user intent while they work.

Overview

dsh-requirements-alignment turns the user's request into a durable requirement baseline — goal, protected constraints, must-preserve behavior, allowed scope, and settled user decisions — and guards it while the agent executes. The agent works silently until a step would materially change the task direction; only then does the plugin surface a drift candidate to you, records your decision, and updates the baseline.

Canonical alignment state lives in the durable AlignmentStateStore sidecar — an official storage-domain domain over the storage-json backend — never in session events. The DSH Session log holds only official DSH-recognizable events, so a bare DSH build (without this plugin) reads any new session, and resume, fork, and compaction recover the same state. The alignment/* event vocabulary is kept solely for legacy compatibility, migration, and test/fold fallbacks; production never appends it.

You decide the direction. The agent decides the engineering.

Requirements Alignment vs Plan Mode

Plan Mode asks:            "Is this the right implementation plan?"
Requirements Alignment asks: "Are we still solving the right problem?"

Plan Mode prevents a bad plan from starting. Requirements Alignment prevents a good plan from drifting.

Plan Mode is the official review-approve step before implementation. Requirements Alignment is intent continuity during execution. They compose: plan, approve, execute — and this plugin keeps the execution on the approved direction. It never modifies plan mode, exit_plan_mode, or any @deepseek-ai/* core package.

How it works

Installation

# from anywhere; path is anchored to your invoking directory
dsh plugin --profile web add <path-to-this-checkout>
# or from the registry once published
dsh plugin --profile web add dsh-requirements-alignment

The plugin is a profile bundle (dsh.bundle.patch + cordis.patch.yml), so it installs through the standard plugin mechanism and adds two rows:

• requirements-alignment — the controller (policy section, /align, /align-mode, both tools);
• requirements-alignment-ask-user — the model-facing question tool.

Quick Start

Install the bundle and start a normal DSH task. Auto mode is enabled by default; clear tasks run with zero interruption, and you are only asked when the execution is about to change direction.

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

Use /align any time you want to inspect whether the current execution still matches the requirement baseline.

Choose how alignment runs

Alignment mode is a three-layer model that can change at runtime without a profile restart:

valid persisted override  ->  valid profile default  ->  auto

- id: requirements-alignment
  name: dsh-requirements-alignment
  config:
    mode: auto          # profile default; a runtime override wins over this

• Profile Default — the composition layer. It is the fallback when no override exists. Changing it (or the override) never rewrites the other; switching modes never edits the profile YAML.
• Runtime Override — switching Auto → Manual → Off at runtime is persisted through the DSH Settings service, so a DSH restart restores effective = your last override. An invalid persisted value (for example a hand-edited mode: banana) never fails startup: the plugin falls back to the profile default and repairs the document once.
• Reset to Profile Default — resetting (a resetMode call or replacing the settings section with {}) drops the override. effective = defaultMode, source = profile. It never re-writes the current effective mode as a new override.

Hot switching — mode transitions are real register/dispose operations (AlignmentRuntime), not a "change the config and restart" step. Auto → Manual → Off → Auto can be cycled live with no duplicates, no listener leaks, and no profile restart. (/align, establish_baseline, report_drift, and /align-migrate are registered or disposed with the mode.) /align-mode is the always-on control command: Off unregisters alignment capabilities but keeps /align-mode so you can switch back.

Runtime Mode backend: implemented. Native Web Settings UI: not implemented (that would need a DSH Core patch). The user-facing switch in this release is /align-mode; the runtime override is also persisted through the official DSH Settings service (@deepseek-ai/dsh-settings), and an external settings.yaml hot edit is picked up live. The profile default remains mode: in the profile bundle.

Auto is the recommended default. Clear tasks run with zero interruption; you are only asked when the execution is about to change direction.

• Auto — the drift-guard policy is in every agent's system prompt. The agent records a light baseline when the request carries protected scope, stays silent otherwise, and calls report_drift only for a real direction change.
• Manual — no automatic policy. The agent works normally until you run /align, which reports status and steers a fresh inspection.
• Off — the plugin stays installed but unregisters alignment capabilities: no policy, no alignment tools, no /align. /align-mode stays so you can switch back to Auto or Manual without editing the profile or settings.yaml.

State is never lost by switching modes

Canonical alignment state (baselines, drifts, decisions, manual checks) lives in the independent AlignmentStateStore sidecar. Switching Auto → Manual → Off → Auto only changes which runtime capabilities are registered; it never deletes a baseline, never deletes the sidecar, never clears state, and never rewrites session events. A baseline established in Auto is still there after Off and back.

Off ≠ Uninstall

mode: off (as profile default or as a runtime override) leaves the bundle in the profile. The row is still loaded, no alignment tools or policy are registered, and you can switch back to Auto or Manual live. That is not the same as uninstalling. (A session that predates the persistence-compatibility fix may still carry legacy alignment/* events in its log; current production never appends them.)

# disable the controller only (leaves the ask-user tool mounted)
#   in the profile's cordis.patch.yml:
#   - id: requirements-alignment
#     disabled: true

# full uninstall — DSH returns to its previous behavior
dsh plugin --profile web rm dsh-requirements-alignment

Every registration is a Cordis effect disposer owned by the plugin's fiber: unloading removes the policy section, the /align + /align-migrate + /align-mode commands, and both tools. Canonical alignment state remains in the durable sidecar. Only sessions written by older versions keep legacy alignment/* events in their log — the current plugin never appends them to live sessions.

Auto mode (default)

The policy section is present in every agent's system prompt. Behavior at task start:

• Clear request with protected scope ("Fix the form bug without changing the UI or public API") — the agent records a light baseline with establish_baseline (silent) before the first substantive edit, pinning the constraints, then works. No user question is involved.
• Trivial request ("Fix the typo in README.md") — nothing is recorded; the agent just works.
• No baseline can be formed (greenfield / vague: new product, undefined form, scope, or interaction) — the agent asks the ONE highest-priority direction question via ask_user_question, records the baseline, and works.

During execution the agent is fully silent unless an action would materially change the baseline (drift). There are no periodic checks, no tool-call counting, no per-file questions. When a drift candidate appears, the agent calls report_drift before acting; the tool result names your exact choice back to the agent (the note and any required baseline change), it records the outcome and, if you approved or revised the direction, the baseline advances to the next revision. The same choice is projected in the per-session baseline summary, so an interrupted or crashed run that resumes knows exactly what you picked without asking again.

A delegated instruction such as "pick whatever makes sense" does not waive the one start question for a greenfield idea.

Manual /align

# profile cordis.patch.yml (or a --patch overlay):
- id: requirements-alignment
  config:
    mode: manual

Manual mode contributes no policy section — the agent works normally until you invoke the command:

/align

/align records the inspection, reports the current alignment status, and steers a fresh alignment check into the agent (which may then run the drift protocol if it finds a candidate). It never takes over the workflow and never blocks execution. The steered check uses the durable sidecar baseline, not the session event log.

/align-mode          # show effective / profile default / runtime override
/align-mode manual   # persist a runtime override and hot-switch now
/align-mode reset    # drop the override; return to the profile default

Example interaction

User:  Fix the submit bug. Don't change the UI or the public API.
Agent: [records the baseline silently, fixes the bug — no questions]

User:  The result-page filter is the only thing to improve. Do not refactor backend logic.
Agent: [working… discovers the backend filter itself is broken and a correct fix would
       need backend changes]
Agent: [report_drift → you are asked]
User:  Stay within the current scope.
Agent: [improves the UI only, leaves the backend untouched]

User:  The app is single-user and local-only. Now make it work across devices.
Agent: [detects an architecture shift]
Agent: [report_drift → you are asked]
User:  Approve the direction change — multi-user with accounts and cloud sync.
Agent: [records the updated baseline (revision advances) and implements]

A long task that waits, then continues

When a step needs you, the agent asks and waits instead of guessing. The session below is a real run of a long publish: the log shows the agent asking you to finish browser authorization, then continuing after you did.

What the session log can prove: the agent asked the user to complete browser authorization for publish and waited for an answer; after the user completed authorization, the publish job finished with exit 0 and the session continued. The log does not record a later registry listing or any outcome beyond that job's exit code.

Drift taxonomy

The plugin records one of these reasons on every drift candidate:

What never triggers alignment

The agent decides autonomously: filenames, helper placement, variable naming, map vs loop, routine refactors, formatter, lint, test placement, ordinary library use, the repository's established stack, small internal designs that do not change observable behavior, in-scope bug fixes, and necessary test additions.

Subagents

DSH child agents cannot ask the user (ask_user_question and report_drift reject with DELEGATED_CALLER for owned children). A child that would need to change the baseline does not decide: it includes a Requirement drift candidate block — reason, current baseline, required change, decision needed — in its final report (or the report tool when available). The parent owns the user interaction and runs the drift protocol.

Configuration

Unknown config keys fail at load (same stance as dsh-plan-mode).

Safety boundary

• No Core modifications. Zero changes to @deepseek-ai/* packages; the only host-side file touched is the profile's bundle list / patch, which is exactly the mechanism DSH provides for installing plugins.
• Question channel + durable sidecar. The plugin never inspects the user's workspace files. It writes alignment state to the official storage-domain sidecar, persists a runtime mode override through the DSH Settings service when one is mounted, and steers one user message on /align. Production never appends alignment/* session events.
• No file access. It does not inspect the filesystem itself; the agent does that with its own tools under the normal sandbox.
• No background monitoring. Drift detection is model-driven policy, not a watcher; there is no periodic interruption loop.

Limitations

• Soft guard, not a hard gate. Whether an action is a drift candidate is the model's judgment (that is the product design: "user decides direction, agent decides engineering"). The plugin records and re-aligns; it does not block execution. A future mode: guard can build on the same events (the fold already derives drift-pending and baseline-update-pending) without changing the architecture.
• Natural drift detection is model-driven. In natural runs (no protocol instruction in the task), a mid-task user direction change triggers report_drift in a fraction of runs (measured honestly in the acceptance report: 3/4 in the RC benchmark); agent-detected constraint conflicts are more reliable. The policy is written to maximize the natural rate; the mechanism itself is deterministic once invoked.
• /align needs a command adapter. UI-less spines (the headless profile, ACP automation) do not dispatch slash commands; the command is exercised by the Web client and by the unit tests / dogfood driver.
• Subagents cannot ask the user. They report drift candidates to the parent, which owns the interaction.
• Baseline content is model-produced. The fold is deterministic; what the model records as the baseline is the model's reading of the task. Keep prompts explicit when the direction matters.
• Sidecar grows append-only. Every baseline, drift, decision, and manual check appends a whole-state checkpoint; there is no pruning yet. Very long sessions with many /align runs accumulate checkpoints (reads stay O(1) at the head, storage grows with the mutation count).
• No Web status projection. Alignment status is surfaced through /align text and the per-session policy summary; there is no client-side status card or projection yet.
• No session-scoped mode in v0.3.0. /align-mode changes the shared plugin/Profile runtime override, not only the calling session. A session-scoped selector is planned for v0.4.0 in docs/ROADMAP.md.

Testing and verification

The release gate runs type checking, linting, a production build, and the Node test suite:

pnpm run check

Real DSH dogfooding boots real dsh profiles with an isolated DSH_HOME. Three run modes keep development fast and honest:

powershell -File scripts/dogfood.ps1 -Smoke        # development: 02-typo, 03-bugfix, 04-scope-drift, 09-drift-choice
powershell -File scripts/dogfood.ps1 -Scenario 12-interrupt-revise   # one scenario
powershell -File scripts/dogfood.ps1               # FULL correctness suite (RC gate): 01..12 minus the 05 benchmark
powershell -File scripts/dogfood.ps1 -Benchmark05  # natural benchmark: 3 runs, reports NATURAL DRIFT TRIGGER N/M

-FailFast aborts at the first failed check; -TimeoutSec <n> (default 600) is a hard per-scenario timeout that kills the process tree. Scenario tasks for natural-behavior cases (03, 04, 05) contain NO protocol instructions; protocol-forced mechanism cases (01, 06, 07, 08, 09, 10, 11, 12) are reported separately — the natural drift trigger rate is its own metric, never presented as a mechanism verification. The full suite must run under danger-full-access (see docs/PROJECT-MEMORY.md).

The packed-artifact smoke packs the current tarball, installs it into a disposable profile, boots Auto → Manual → Off (/align, establish_baseline, and the policy section are asserted from the assembled system prompt and live registries — not a loose word match), removes it, and verifies the profile restores cleanly:

powershell -File scripts/packed-smoke.ps1

The v0.2.1 release gate verified:

• Core modifications: 0
• Node tests: 91/91 passing
• Packed add/rm smoke: 34/34 — Auto → Manual → Off against the current v0.2.1 tarball
• v0.2.0 dogfood baseline (unchanged protocol): 63/63 checks passing (11 scenarios); natural drift trigger 3/4

The v0.2.2 persistence-compatibility gate verified:

• Core modifications: 0
• Node tests: 133/133 passing (2 statusCache session-identity + 3 align-driver lazy-resolution regressions)
• Targeted store / persistence / migration regression suites: 29/29 passing
• Align-driver regression: apply() before the controller exists → later reads resolve the sidecar (revision 1), never the legacy fold
• Real dogfood 01-greenfield / 02-typo / 03-bugfix: PASS (03 asserts baseline recorded + revision >= 1)
• npm pack --dry-run passes (exports targets all present; no v0.3.0 runtime-mode / hot-switch files)
• DSH rc.6: KNOWN_SESSION_EVENT_TYPES = 44, alignment/* = 0 official known event types

The v0.3.0 runtime-mode / hot-switching gate verified:

• Core modifications: 0
• Node tests: 176/176 passing (v0.2.2 suite plus ModeStore, AlignmentRuntime, hot-switch, first-start rollback, external-failure, /align-mode, sidecar fold)
• Hot-switch matrix: Auto → Manual, Manual → Auto, Auto → Off, Off → Auto, Manual → Off, Off → Manual — PASS (live register/dispose, exactly-one capability sets, no duplicates after repeated cycles)
• Persistence independence: a baseline recorded in Auto survives Auto → Manual → Off → Auto
• Runtime override persistence: startup restores a persisted override; reset returns to the profile default (effectiveSource = profile); an invalid persisted override falls back and repairs
• Rollback: transition failure restores the prior mode; a settings persistence failure compensates the runtime back (no split-brain)
• Persistence regression suite (cold resume, fork, historical fork, compaction, legacy migration): PASS — production writer still emits zero alignment/* events
• Current-tarball packed add/boot/remove: 40/40 — clean profile with no source link; Auto / Manual / Off registries, /align, /align-mode, direct establish_baseline, uninstall, and manifest restoration verified. External model completion was unavailable (QUOTA: Insufficient Balance) and is reported separately rather than claimed as an E2E pass.

Detailed evidence and the bounded-run caveat are recorded in ACCEPTANCE.md.

Development

pnpm install          # dependencies
pnpm run typecheck    # tsc (src + test)
pnpm run lint         # eslint (src + test)
pnpm run build        # tsc → lib/
pnpm test             # node:test
pnpm run check        # all of the above

Real dogfooding (boots real dsh profiles with an isolated DSH_HOME; smoke mode for development, full suite + natural benchmark + packed add/rm smoke for the RC gate):

powershell -File scripts/dogfood.ps1 -Smoke
powershell -File scripts/dogfood.ps1               # full correctness suite (RC gate)
powershell -File scripts/dogfood.ps1 -Benchmark05  # natural drift benchmark
powershell -File scripts/packed-smoke.ps1          # packed add/rm smoke (RC gate)
# run a single scenario:
powershell -File scripts/dogfood.ps1 -Scenario 05-arch-shift

See docs/ARCHITECTURE.md for the design decisions and the exact capability seams used.

Compatibility

• DeepSeek Harness 0.1.0-rc.6 (verified against the local profile bundle set and the npm registry releases of the same version).
• @deepseek-ai/cordis 4.x, @deepseek-ai/dsh-* ^0.1.0-rc.6.
• Windows (verified) and POSIX (no platform-specific code).
• Old v0.1 sessions fold safely: legacy alignment/status events still count as manual checks, and a session without the new events simply reports revision 0 / "unknown" instead of crashing.

License

MIT. See LICENSE.