dsh-completion-guard 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project are documented here. The project is pre-1.0; release versions track the plugin lifecycle, not stabilised API promises.
 
+## 0.4.0 - 2026-09-02
+
+### Added
+
+- **DSH alpha.3 is the 0.4.0 implementation baseline.** Version 0.4.0 targets DSH `0.1.2-alpha.3` with dshmarket `1.39.0` and Cordis `4.0.2`.
+- **A proof must refer to the work that is still pending and to evidence for the action the user actually requested.** A read or verification result for another target cannot close the item. Empty subject sets, evidence imported from another session, and evidence with the wrong kind, surface, subject, or outcome are rejected.
+- **Damaged proof state fails closed.** Changing the recorded asset set or scope digest makes the proof unusable. The technical contract versions canonical projections, bounded subject readback, scope coverage, state verification, and replayable `sessionQuery` state while excluding raw private logs and asset bytes.
+- **Stage disposition.** The stopped 0.3.3 compatibility candidate is recorded as `superseded_before_candidate`; no 0.3.3 source, artifact, installation, native acceptance, commit, tag, or release existed.
+
+### Changed
+
+- **Compatibility adaptation pauses after alpha.3.** Version 0.4.0 stays frozen on the DSH alpha.3 setup. Alpha.4 and later alpha releases are not new adaptation targets; work resumes with the first upstream RC published after alpha.3. Upstream milestones are listed on the [DeepSeek Harness tags page](https://github.com/deepseek-ai/deepseek-harness/tags).
+
+### Validation
+
+- The release commit passes the repository matrix and CI on Ubuntu, macOS, and Windows with Node.js 22 and 24. One frozen 26-file tgz is used for native macOS and Windows acceptance and npm publication; the GitHub Release carries its checksum and platform annexes.
+- Earlier 0.4.0 candidate packages remain historical evidence only. Results never transfer to changed package bytes; see [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md).
+
+## 0.3.2 - 2026-09-01
+
+### Added
+
+- **Two exact DSH setups are recognized.** The `0.1.1-rc.2` + dshmarket `1.36.0` and `0.1.2-alpha.2` + dshmarket `1.38.1` package sets are both checked on macOS and Windows.
+- **The whole package set must match.** Every required package must appear once with the expected version and integrity. Missing, mixed, duplicate, unidentified, or unknown packages make the entire host unavailable instead of leaving part of the Guard enabled. Status now lists missing packages, and switching setups invalidates earlier completion certificates.
+
+### Changed
+
+- Peer dependencies accept only the two checked version sets (`0.1.1-rc.2 || 0.1.2-alpha.2`, Cordis `4.0.1 || 4.0.2`). A source comparison found no change in the DSH events, Goal calls, tool definitions, or terminal results that the Guard uses.
+
+### Fixed
+
+- **Release packaging now works with Windows tar.** Archive extraction uses paths relative to the temporary working directory instead of passing absolute archive paths, without changing the files placed in the package.
+
+### Validation
+
+- Candidate commit `22cde610` passed the six-job Ubuntu, macOS, and Windows CI matrix on Node.js 22 and 24. The complete 20-file suite passes 359 tests with one Windows-only skip on macOS, and native Windows matched all 34 alpha.2 package rows with no missing, extra, or duplicate entries.
+- The frozen 26-file package (181157 bytes, SHA-256 `feb7fc29799820e08dfe6d2bdb94823e745df9b5aa7c34d46262e5df30dabac4`) passed the same-byte isolated Web and Headless lifecycle on native macOS and Windows. The annotated tag, npm package, GitHub Release, and downloaded public bytes all resolve to the same commit and artifact; see [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md).
+
 ## 0.3.1 - 2026-08-31
 
 ### Fixed
@@ -11,29 +49,29 @@ All notable changes to this project are documented here. The project is pre-1.0;
 
 ### Validation
 
-- Focused release-pack tests cover exact-HEAD injection, repeated-pack byte identity, checksum/record output, and dirty-tree rejection. The 0.3 runtime and digest bytes are otherwise unchanged; the final 0.3.1 tgz requires exact-byte macOS and native Windows acceptance before publication.
+- The frozen 0.3.1 package passed native macOS and Windows lifecycle checks, was published to npm, and has a matching GitHub Release. Exact artifact and public readback evidence is recorded in [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md).
 
 ## 0.3.0 - 2026-08-31
 
 ### Added
 
-- **v0.3 semantic completion gates.** Adds exact paired optional Goal state/tool peers, an injected exact-version/integrity action/platform host lock, versioned action/Git/supported-host manifests, authority-aware contract segmentation, typed boundaries, structured checkpoint diagnostics, and digest-v3 certificates bound to session, host, contract, evidence, binding, expected transition, and optional Goal identity.
-- **Stateful action readback.** `install`, `apply`, `create`, `modify`, `restart`, `commit`, `push`, `publish`, `pull`, and `fetch` require distinct resolution, effect, and independent state evidence with same-target role closure. Generic-run evidence cannot authorize a v0.3 user-level completion; legacy generic-run certificates remain audit history only.
-- **Explicit read-only and mutation tools.** `context_guard_evidence` never mutates; `context_guard_action` owns exact-tgz package/registry effects, two-phase dshmarket restart, and exact Git effects only after an exact pending root requirement/revision, complete action-specific requested identity, target digest, host identity, executable identity, and live prestate all match. Prohibitions/acceptances cannot authorize effects; v0.3 package versions and Git refs are exact-only.
+- **High-impact changes must match the user's exact request.** Package, file, service, and Git operations are tied to one target and an expected result. A generic successful command cannot certify a different action.
+- **Changes require independent readback.** Install, apply, file editing, restart, Git, and publish operations must show both the intended effect and the resulting saved state before they can close a requirement.
+- **Read-only checks and mutations use separate tools.** Looking up a target never grants permission to change it. Mutations require a current, matching root-user instruction; prohibitions and acceptance checks cannot provide that authority.
 - **Bilingual npm download history.** A daily cumulative chart keeps the renamed `dsh-context-guard` and current `dsh-completion-guard` package totals separate while presenting one project-growth line. Collection reconciles npm range and point responses before publishing English and Simplified Chinese SVGs.
 
 ### Fixed
 
-- Assistant prose no longer controls turn stopping. Goal continuation remains owned by the Goal Round Driver; only persisted, qualified typed boundaries can trigger post-commit same-ref disarm readback.
-- Unknown, missing, or drifted host identities fail closed. The Guard-owned `update_goal(action=complete)` path is checked before mutation; trusted in-process direct Goal/session writes are detected as integrity violations but are not claimed to be preventable.
-- Active host identity is supplied before certificate replay, managed host-lock injection is idempotent, DSH folded-YAML SRI output is parsed exactly, and a fresh profile's sole top-level `[]` sentinel is safely replaced before the managed list is appended.
-- Publish now freezes one canonical HTTPS registry across capture, npm argv, and standard packument readback, with `--ignore-scripts`; create/modify freeze their expected post-effect bytes at resolution time instead of copying the observed digest into the predicate, and modify rejects source-byte drift against its frozen pre-digest.
-- Windows stateful actions now resolve and version-probe audited `.cmd`/`.bat` shims through a closed invocation whose interpreter is pinned to the canonical `SystemRoot\\System32\\cmd.exe` realpath and version. Resolution and effect bind both identities, then execute the same revalidated paths instead of searching `PATH` or trusting a changed `ComSpec`; shell-control and expansion characters remain fail-closed.
+- Assistant wording no longer controls whether DSH continues a task. Only a saved wait or deferral state can end the current round without claiming completion.
+- Missing, unknown, or changed DSH package identities keep the affected Guard capabilities unavailable. Direct internal Goal or session writes are reported as integrity problems but are not claimed to be preventable.
+- Host-lock injection is repeatable, folded YAML integrity values are read correctly, and a fresh empty profile can be updated safely.
+- Package publishing and file edits bind the expected destination before making a change and reject changed input or different resulting bytes.
+- Windows actions pin both the command wrapper and the system command interpreter, then reuse those checked paths instead of searching again at execution time.
 - The npm statistics publisher now rejects non-default refs before checkout, isolates read-only collection from the write-capable publication job, does not persist credentials during collection, and pins all official Actions to immutable commits.
 
 ### Changed
 
-- **Package renamed from `dsh-context-guard` to `dsh-completion-guard`.** An unrelated DSH plugin (kpl0111/dsh-context-guard, tool-result pruning) already uses the name; the rename removes the collision for name-keyed registries and lists. The internal Cordis bundle id stays `context-guard`, so installed profiles keep their runtime identity. The previous npm package `dsh-context-guard` will be deprecated once `dsh-completion-guard` is published.
+- **Package renamed from `dsh-context-guard` to `dsh-completion-guard`.** An unrelated DSH plugin already uses the old name. The internal Cordis bundle id stays `context-guard`, so installed profiles keep their runtime identity; all published versions of the previous npm package are deprecated and point readers to the new package.
 
 ### Validation
 

package/CHANGELOG.zh-CN.md

@@ -2,6 +2,44 @@
 
 本项目的重要变化记录在这里。项目仍处于 1.0 之前；版本号跟踪插件生命周期，不代表 API 已稳定。
 
+## 0.4.0 - 2026-09-02
+
+### 新增
+
+- **DSH alpha.3 成为 0.4.0 的实现基线。** 0.4.0 面向 DSH `0.1.2-alpha.3`、dshmarket `1.39.0` 和 Cordis `4.0.2`。
+- **证明必须对应仍在待办中的工作，也必须对应用户实际要求的操作。** 读取或验证了另一个对象，不能关闭当前事项。对象集合为空、从其他会话带入证据，或证据的类型、表面、对象、结果不匹配时，都会被拒绝。
+- **证明状态被篡改时保持失败关闭。** 资产集合或范围摘要一旦被改动，这份证明就不能再使用。技术层面会版本化 canonical projection、有限 subject readback、scope coverage、state verification 和可重放的 `sessionQuery` 状态，但不保存原始私有日志或资产字节。
+- **阶段处置记录。** 已停止的 0.3.3 兼容候选明确记为 `superseded_before_candidate`；该阶段不存在 0.3.3 源码、工件、安装、原生验收、提交、tag 或 release。
+
+### 变更
+
+- **alpha.3 之后暂停兼容性适配。** 0.4.0 继续冻结在 DSH alpha.3 环境。alpha.4 及此后的 alpha 版本不作为新的适配目标；上游发布 alpha.3 之后的第一版 RC 时再恢复适配。上游版本进度见 [DeepSeek Harness 标签页](https://github.com/deepseek-ai/deepseek-harness/tags)。
+
+### 验证
+
+- 发布提交通过仓库矩阵，以及 Ubuntu、macOS、Windows 上的 Node.js 22/24 CI。同一份 26 文件 tgz 用于 macOS、Windows 原生验收和 npm 发布；GitHub Release 附带校验和与平台验收记录。
+- 更早的 0.4.0 候选包只保留为历史证据。包字节变化后，旧结果不会迁移到新包；详见 [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md)。
+
+## 0.3.2 - 2026-09-01
+
+### 新增
+
+- **可识别两套精确的 DSH 环境。** `0.1.1-rc.2` + dshmarket `1.36.0` 与 `0.1.2-alpha.2` + dshmarket `1.38.1` 两套包集合均已在 macOS 和 Windows 检查。
+- **必须完整匹配整套包。** 每个必需包都必须恰好出现一次，并具有预期版本和完整性值。缺包、混装、重复、缺少身份或未知包都会让整个宿主保持不可用，不会只启用部分 Guard。状态会列出缺少的包，切换环境也会使旧完成证书失效。
+
+### 变更
+
+- peer dependencies 只接受两套已检查版本（`0.1.1-rc.2 || 0.1.2-alpha.2`，Cordis `4.0.1 || 4.0.2`）。源码对比未发现 Guard 使用的 DSH 事件、Goal 调用、工具定义或终端结果发生变化。
+
+### 修复
+
+- **发布打包现在兼容 Windows tar。** 解包时改用相对于临时工作目录的路径，不再把归档绝对路径传给 tar；包内文件不变。
+
+### 验证
+
+- 候选提交 `22cde610` 已通过 Ubuntu、macOS、Windows 和 Node.js 22/24 的六项 CI 矩阵。20 个测试文件全量通过 359 项，macOS 跳过 1 项仅适用于 Windows 的测试；Windows 原生核对 alpha.2 的 34 行包清单全部匹配，没有缺失、额外或重复项。
+- 冻结的 26 文件包（181157 字节，SHA-256 `feb7fc29799820e08dfe6d2bdb94823e745df9b5aa7c34d46262e5df30dabac4`）已用同一份字节在原生 macOS 和 Windows 完成隔离 Web 与 Headless 生命周期验收。annotated tag、npm 包、GitHub Release 和重新下载的公开文件均指向同一提交与工件；详见 [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md)。
+
 ## 0.3.1 - 2026-08-31
 
 ### 修复
@@ -11,29 +49,29 @@
 
 ### 验证
 
-- 聚焦 release-pack 测试覆盖精确 HEAD 注入、重复打包字节一致、checksum/record 输出以及脏工作树拒绝。除此之外，v0.3 runtime 与 digest 字节不变；最终 0.3.1 tgz 在发布前须完成 macOS 与原生 Windows 的同一字节验收。
+- 冻结的 0.3.1 包已通过 macOS 和 Windows 原生生命周期检查，并已发布到 npm 和对应 GitHub Release。精确工件与公开读回证据见 [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md)。
 
 ## 0.3.0 - 2026-08-31
 
 ### 新增
 
-- **v0.3 语义完成门禁。** 增加 Goal state/tool 成对精确 optional peers、显式注入的 exact version/integrity action/platform 宿主锁、版本化 action/Git/supported-host manifests、按权威分段的合同捕获、typed boundary、结构化 checkpoint 诊断，以及绑定 session、host、contract、evidence、binding、expected transition 与可选 Goal 身份的 digest-v3 证书。
-- **有状态动作独立读回。** `install`、`apply`、`create`、`modify`、`restart`、`commit`、`push`、`publish`、`pull`、`fetch` 必须提供不同 ID 的 resolution、effect 与独立 state evidence，并完成同目标 role 闭合。generic-run 证据不能授权 v0.3 用户级完成；旧 generic-run 证书只保留为审计历史。
-- **显式只读/变更工具。** `context_guard_evidence` 永不执行 mutation；`context_guard_action` 仅在精确的 pending 根用户 requirement/修订、完整动作身份、target digest、宿主身份、可执行文件身份和 live prestate 全部匹配后，才执行 exact-tgz package/registry effect、两阶段 dshmarket restart 或精确 Git effect。prohibition/acceptance 不得授权 effect；v0.3 package 版本与 Git ref 仅支持 exact。
+- **高影响变更必须匹配用户的精确要求。** 包、文件、服务和 Git 操作会绑定到一个目标和预期结果；普通命令成功不能替代另一个动作的完成证据。
+- **变更后必须独立读回。** 安装、更新、文件修改、重启、Git 和发布操作需要同时证明预期动作与最终保存状态，才能关闭要求。
+- **只读检查和实际变更使用不同工具。** 查询目标不会自动产生修改权限。变更必须对应当前根用户要求；禁止项和验收条件不能提供这份授权。
 - **双语 npm 下载量历史。** 每日累计图分别保留更名前的 `dsh-context-guard` 与当前 `dsh-completion-guard` 包总量，同时呈现一条项目增长曲线。采集器会先核对 npm range 与 point 响应，再发布英文和简体中文 SVG。
 
 ### 修复
 
-- assistant 散文不再控制 turn stopping。正常 Goal 续行仍只由 Goal Round Driver 调度；只有已持久化且资格成立的 typed boundary 才能在提交后触发同 Goal ref 的 disarm 双读回。
-- 未知、缺失或漂移的宿主身份一律 fail-closed。Guard 自己注册并守卫的 `update_goal(action=complete)` 路径在 mutation 前检查；可信进程内直接写 Goal/session 的旁路只记录 integrity violation，不声称能够阻止。
-- 活动 host identity 会在 certificate replay 前传入；managed host-lock injection 保持幂等；DSH folded-YAML SRI 输出会被精确解析，新 profile 唯一的顶层 `[]` sentinel 会在追加 managed list 前安全替换。
-- Publish 现在会在捕获、npm argv 与标准 packument readback 之间冻结同一个 canonical HTTPS registry，并显式使用 `--ignore-scripts`；create/modify 在 resolution 阶段冻结预期 post-effect 字节，不再把 observed digest 回填为谓词，且 modify 会按冻结 pre-digest 拒绝源字节漂移。
-- Windows 有状态动作现在通过封闭调用解析并探测已审计 `.cmd`/`.bat` shim 的版本，其中解释器固定为 canonical `SystemRoot\\System32\\cmd.exe` realpath 与版本。resolution/effect 同时绑定 shim 与解释器身份，执行时复用经重校验的路径，不再二次搜索 `PATH` 或信任已变化的 `ComSpec`；shell 控制字符与展开字符继续 fail-closed。
+- 助手措辞不再决定 DSH 是否继续任务。只有已保存的等待或延期状态才能结束当前轮次，同时保留未完成要求。
+- DSH 包身份缺失、未知或发生变化时，受影响的 Guard 能力保持不可用。进程内部直接写 Goal/session 会被报告为完整性问题，但不声称一定能够阻止。
+- 宿主身份注入可重复执行，折叠 YAML 中的完整性值可以正确读取，新建空 profile 也能安全更新。
+- 包发布和文件修改会在操作前绑定预期目标，并拒绝已变化的输入或不同的最终字节。
+- Windows 操作会固定命令包装器和系统命令解释器，执行时复用已检查路径，不再重新搜索。
 - npm 统计发布器现在会在 checkout 前拒绝非默认 ref，把只读采集与具有写权限的发布 job 隔离，采集阶段不持久化凭据，并把全部官方 Action 固定到不可变提交。
 
 ### 变更
 
-- **包名由 `dsh-context-guard` 更名为 `dsh-completion-guard`。** 无关的 DSH 插件(kpl0111/dsh-context-guard,工具结果剪裁)已占用该名称;更名消除按名字建索引的注册面与列表上的冲突。内部 Cordis bundle id 保持 `context-guard` 不变,已安装 profile 的运行时身份不受影响。`dsh-completion-guard` 发布后,原 npm 包 `dsh-context-guard` 将被 deprecate。
+- **包名由 `dsh-context-guard` 更名为 `dsh-completion-guard`。** 另一个无关 DSH 插件已经使用旧名称。内部 Cordis bundle id 仍为 `context-guard`，已安装 profile 的运行时身份不受影响；旧 npm 包的所有已发布版本均已标为弃用，并引导读者使用新包。
 
 ### 验证
 

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md)
 
-A task-contract and completion-certification plugin for DeepSeek Harness (DSH). It preserves requirements, prohibitions, acceptance criteria, later corrections, and bounded evidence so a task can be certified only when current successful evidence matches the current contract.
+An add-on for DeepSeek Harness (DSH) that keeps a task's requirements and checks them before the task is marked complete. It restores the same checklist after a resumed session and accepts only matching saved tool results as evidence.
 
 ![Task-contract clauses and bounded evidence pass through a checkpoint before a completion certificate is issued](assets/social/completion-guard-hero.png)
 
@@ -11,89 +11,74 @@ A task-contract and completion-certification plugin for DeepSeek Harness (DSH).
 Install the published plugin into a DSH Web profile:
 
 ```sh
-dsh plugin --profile web add dsh-completion-guard@0.3.1
+dsh plugin --profile web add dsh-completion-guard@0.4.0
 ```
 
-Restart DSH Web, open a session, and enable the guard:
+Before restarting DSH, record and verify the active runtime and profile. Replace the example paths with the absolute paths on your machine:
 
-```text
-/context-guard on
-/context-guard status
-```
-
-Activation is opt-in by default. `status` reports whether the guard is enabled, the current epoch and contract revision, pending and passed item counts, the evidence count, and integrity state. `off` stops capture and gating for the session while preserving its prior history; `clear` supersedes every pending requirement/acceptance under a `CLEAR:` sentinel (prohibitions retained) so an empty-binding checkpoint can certify while the guard stays on; `diagnose` returns a bounded diagnostic view.
-
-### Activation modes
+```sh
+DSH_RUNTIME_ROOT=/absolute/path/to/.dsh-runtime
+DSH_PROFILE_ROOT=/absolute/path/to/.dsh/profiles/web
+DSH_COMPOSED_DUMP=/tmp/dsh-web-composed.yml
+GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-lock"
 
-`activation` accepts two values:
+"$GUARD_HOST_LOCK" inspect --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
+"$GUARD_HOST_LOCK" inject --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
+dsh --profile web --dump-config > "$DSH_COMPOSED_DUMP"
+"$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config "$DSH_COMPOSED_DUMP"
+```
 
-| Value | Behavior |
-| --- | --- |
-| `opt-in` | Default. A session remains unprotected until `/context-guard on` is recorded in that session. |
-| `always` | Starts enabled before the session log is replayed. `/context-guard off` disables the guard for that session until a later `/context-guard on`. |
+On Windows, run the same three subcommands through `dsh-completion-guard-host-lock.cmd` in the profile's `node_modules\.bin` directory and use Windows absolute paths. Repeat this check after a DSH, profile, or package upgrade. The Guard stays unavailable if the active package set is missing, mixed, duplicated, or different from a checked setup.
 
-To start Context Guard automatically for sessions in a DSH profile, add an ID-targeted override to that profile's `cordis.patch.yml`. For the default Web profile on macOS or Linux, this file is normally `~/.dsh/profiles/web/cordis.patch.yml`:
+Restart DSH Web, open a session, and enable the Guard:
 
-```yaml
-- id: context-guard
-  name: dsh-completion-guard
-  config:
-    activation: always
+```text
+/context-guard on
+/context-guard status
 ```
 
-Restart that DSH profile after changing the configuration, then run `/context-guard status` in a session to confirm that the guard is enabled. Because `always` enables the guard before replay, applying it to a profile that already has persisted sessions can cause earlier user messages in those sessions to be captured when their logs are rebuilt. Use `opt-in` when protection should begin only after an explicit per-session command.
-
-Once enabled, Context Guard captures direct user requirements and acceptance criteria. Tool results become citable evidence only after DSH persists them. Before the model claims the whole task is complete, it must call the injected `context_guard_checkpoint` tool with matching evidence IDs; an incomplete or stale binding cannot certify completion.
+Activation is opt-in by default. `status` shows whether the Guard is on and how many checks remain. `off` stops protection for the current session without deleting its history. `clear` closes the current checklist while keeping prohibitions. `diagnose` explains why a completion check passed or failed.
 
 ## What it protects
 
-- Captures requirement, acceptance, and prohibition clauses with stable identities and append-only supersession.
-- Derives bounded, redacted evidence from persisted DSH tool calls and results.
-- Requires method, operation, subject, surface, and outcome to match where the contract makes them explicit.
-- Re-verifies certificates when a session is rebuilt or resumed and fails closed on integrity loss.
-- Blocks the Guard-owned model-tool Goal completion path while enabled unless a current certificate exists; trusted in-process direct Goal/session writes are detected as integrity violations, not universally prevented.
+- Saves requirements, acceptance checks, prohibitions, and later corrections without overwriting history.
+- Uses only tool calls and results that DSH has saved, and stores a redacted summary rather than full output.
+- Accepts evidence only when the action and result match the requested command, file, or other target.
+- Rechecks completion after a session is rebuilt or resumed, and refuses to certify damaged state.
+- Stops the Guard-owned Goal completion path when the current checklist has not passed. DSH internals can still bypass this path, so the plugin reports those cases rather than claiming to block every possible write.
 
 ## Status and compatibility
 
-Version 0.3.1 is the current release line. Its [npm package](https://www.npmjs.com/package/dsh-completion-guard) and [GitHub release](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.3.1) are authoritative only when the exact-artifact public readback recorded in [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) is complete. Verify those linked identities before installing.
-
-The `0.3.0` npm artifact passed same-byte native validation, but npm omitted its required `gitHead` metadata because a prebuilt tgz was published. Its version identity cannot be reused, and no GitHub Release is created for `v0.3.0`; `0.3.1` preserves the runtime behavior while repairing the release provenance path.
-
-> The project was renamed from `dsh-context-guard` to `dsh-completion-guard` on 2026-08-29 to avoid a name collision with an unrelated DSH plugin (kpl0111/dsh-context-guard, tool-result pruning). The internal Cordis bundle id stays `context-guard`, and the previous npm package `dsh-context-guard` will be deprecated in favor of this package. It targets DSH `0.1.1-rc.2`, Node.js `>=22`, and pnpm `>=11`.
-
-### Earlier v0.2.x evidence
+Version 0.4.0 is the current release. Install it from [npm](https://www.npmjs.com/package/dsh-completion-guard); its [GitHub Release](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.4.0) carries the exact package checksum and native macOS and Windows acceptance records. It targets DSH `0.1.2-alpha.3` with dshmarket `1.39.0` and Cordis `4.0.2`.
 
-The 0.2.1 release suite contains 138 tests (105 domain/core). It attributes shell evidence to the session cwd when the tool omits `workdir`, supports literal `2>&1` diagnostics and read-only inspection commands, maps process verbs to run evidence, and exposes actionable hints when a checkpoint binding is rejected. 0.2.1 adds a session-layer capture filter so clarification questions, meta comments, and bare progression phrases (`继续`, `continue`) never become contract items; de-duplicates repeated recovery notifications; adds `/context-guard clear`; and documents how a goal completes when the guard is disabled or blocked. A macOS live Web run loaded the published profile package and certified a real `pnpm test` result.
+Version 0.3.2 remains available for the checked DSH `0.1.1-rc.2` and `0.1.2-alpha.2` setups. Do not combine packages from different checked setups; the Guard fails closed when the active package set does not match one complete cohort in [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
 
-The Windows TEMP readback verifies the `b75868e9e73d29f50530ddaba15cfaef82e03ece` source matrix and the exact-source tarball → isolated installation → dump-config → Web startup log and cleanup chain. HTTP 200 appeared only in the first-run stdout, was not persisted, and was not rerun during readback, so the HTTP response itself is not independently confirmed. A real model-session smoke remains not run.
+Version 0.4.0 remains frozen on this alpha.3 setup. Alpha.4 and later alpha releases are not new adaptation targets; compatibility work resumes with the first upstream RC published after alpha.3. Track that milestone on the [DeepSeek Harness tags page](https://github.com/deepseek-ai/deepseek-harness/tags).
 
-### v0.3.1
+Release packages are built once from a clean commit and published only after those exact bytes pass native macOS and Windows Web and Headless checks. CI, native lifecycle checks, package publication, and public readback remain separate evidence scopes; see [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md).
 
-Version 0.3.1 carries the v0.3 semantic action/target binding, independent state readback for stateful actions, typed boundaries, digest-v3 certificates, exact active-host identity, and paired optional Goal integration introduced in 0.3.0. It adds a deterministic release packer that binds the full Git HEAD inside the frozen tgz before native-platform acceptance and registry publication. The 19-file deterministic suite passed 351 tests with one Windows-only capability skip on macOS and all 352 tests without skips on native Windows for the unchanged runtime baseline. [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) keeps source, artifact, CI, model-session, and publication evidence scopes separate.
+Version 0.3.0 is not recommended. Its package passed native checks, but npm did not record the required source commit, so the version cannot be repaired in place and has no GitHub Release. Use 0.3.2.
 
-The release uses [`manifests/action-manifest.v1.json`](manifests/action-manifest.v1.json), [`manifests/git-command-manifest.v2.json`](manifests/git-command-manifest.v2.json), and [`manifests/supported-host.v1.json`](manifests/supported-host.v1.json). Goal integration requires the exact optional peers `@deepseek-ai/dsh-goal@0.1.1-rc.2` and `@deepseek-ai/dsh-tool-goal@0.1.1-rc.2` together. It fails closed unless the active DSH runtime/profile graph injects the exact `hostLockPackages`, platform, and profile identity. A nearest lockfile is not accepted because DSH core and profile plugins use separate package graphs. The default bundled patch deliberately contains no fabricated lock.
+> The project was renamed from `dsh-context-guard` to `dsh-completion-guard` on 2026-08-29 because an unrelated plugin already used the old name. The internal bundle id remains `context-guard`, and the old npm package points users to this one. Supported DSH setups are listed in [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md); Node.js `>=22` and pnpm `>=11` are required.
 
-After installing the release into a profile, generate and verify its active identity with the packaged CLI. Use absolute paths for the actual DSH installation; the dump is an inspection artifact, not a configuration source:
+## Activation modes
 
-```sh
-DSH_RUNTIME_ROOT=/absolute/path/to/.dsh-runtime
-DSH_PROFILE_ROOT=/absolute/path/to/.dsh/profiles/web
-DSH_COMPOSED_DUMP=/tmp/dsh-web-composed.yml
-GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-lock"
+The default `opt-in` mode protects a session only after `/context-guard on`. To enable the Guard automatically for a DSH profile, add this override to that profile's `cordis.patch.yml`:
 
-"$GUARD_HOST_LOCK" inspect --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
-"$GUARD_HOST_LOCK" inject --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
-dsh --profile web --dump-config > "$DSH_COMPOSED_DUMP"
-"$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config "$DSH_COMPOSED_DUMP"
+```yaml
+- id: context-guard
+  name: dsh-completion-guard
+  config:
+    activation: always
 ```
 
-`inspect` and `inject` reject missing, duplicate, multi-version, or drifted critical packages. `verify-dump` then proves that DSH composed the same bounded tuple that was read from the active graphs. Repeat the flow after any DSH/profile/package upgrade. Until it succeeds, certification, Goal-dependent completion, and affected action capabilities remain unavailable. Release validation used fresh isolated profiles and did not overwrite the user's existing DSH profiles.
+Restart the profile, then run `/context-guard status`. In `always` mode, rebuilding an existing session can also capture earlier user messages from its saved log. Keep `opt-in` if protection should start only after an explicit command.
 
-`context_guard_evidence` is read-only: it resolves targets, validates persisted effects, and performs independent state readback. Mutating install/apply/restart/publish and exact Git commit/push/pull/fetch operations use the separately named `context_guard_action` tool. A resolution is not mutation authority: the caller must identify the exact pending root-owned requirement and revision, repeat the persisted target digest, and match every action-specific identity field before any executable, HTTP request, or restart intent runs. Prohibitions and acceptance clauses never authorize mutation. Package/apply/publish authority is exact-version-only in v0.3; Git authority requires an explicit remote and canonical full ref/refspec. The presentation surface shows the canonical target and command-manifest digest before execution.
+## How completion is checked
 
-Publish targets use one canonical HTTPS registry base with no credentials, query, fragment, ambiguous path, or control characters; the same base is frozen in the root contract, npm argv, and registry readback. Create and modify resolutions freeze the expected post-write digest before effect; modify re-hashes the source bytes against the frozen pre-digest before applying the pinned unique UTF-8 replacement semantics, so either prestate drift or different post-effect bytes fail closed.
+Once enabled, the Guard saves direct user requirements and acceptance checks. A saved tool result counts only when it matches the requested command, file, or other target. Before claiming the whole task complete, the model must pass the Guard's checkpoint; missing, stale, or mismatched evidence leaves the task open.
 
-Context Guard recognizes only a small, auditable shell and PowerShell command subset. Unsupported or ambiguous syntax stays incomplete instead of being partially trusted. Compound commands, variables, non-whitelisted executables, file-target redirects, and in-place `sed` remain outside the certifiable surface. See [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for the exact grammar and platform evidence.
+Read-only evidence collection and actions that change packages, files, services, or Git state use separate tools. A successful lookup never grants permission to make a change. Exact command limits and platform evidence are documented in [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
 
 ## Boundaries
 
@@ -103,7 +88,11 @@ Evidence is bounded and redacted. Complete prompts, stdout, file contents, crede
 
 ## Relationship to Codex Context Guard
 
-This project ports deterministic behavior from [`GreenLv/codex-context-guard`](https://github.com/GreenLv/codex-context-guard), with v0.8.8 as its semantic baseline. The two repositories serve different runtimes:
+This project began as a DSH port of deterministic behavior from [`GreenLv/codex-context-guard`](https://github.com/GreenLv/codex-context-guard) v0.8.8. That version is the historical starting point, not the current compatibility level.
+
+Current shared behavior is tracked by pinned conformance fixtures and an explicit delta ledger. Version 0.3.2 includes the shared Stop 2.0, digest v3, and conformance work from the Codex 0.9.4 line. Version 0.4.0 adds the stricter task, path, capability, and proof bindings documented in [`docs/SEMANTIC_COMPATIBILITY.md`](docs/SEMANTIC_COMPATIBILITY.md); this is a bounded semantic alignment claim, not full product parity.
+
+The two repositories serve different runtimes:
 
 - `codex-context-guard` is the Codex Hook/Python implementation with Codex plugin-cache and Hook lifecycle integration.
 - `dsh-completion-guard` is an independent TypeScript implementation over native DSH Session events, commands, tools, and agent lifecycle.
@@ -114,7 +103,7 @@ They do not share runtime state, installers, caches, or release histories. Fixes
 
 ![Combined cumulative npm download growth across dsh-context-guard and dsh-completion-guard](https://raw.githubusercontent.com/GreenLv/dsh-completion-guard/stats/npm-downloads.svg)
 
-The cumulative chart keeps the old and new npm package totals visibly separate, marks the 2026-08-29 rename, and combines them only for the project growth line. npm download counts measure registry requests; they are not counts of unique users or confirmed installations. The workflow runs daily and can also be triggered manually.
+The cumulative chart keeps the old and new npm package totals visibly separate, marks the 2026-08-29 rename, and combines them only for the project growth line. npm download counts measure registry requests; they are not counts of unique users or confirmed installations. The workflow updates the chart daily and can also be triggered manually.
 
 ## Documentation
 
@@ -124,7 +113,8 @@ The cumulative chart keeps the old and new npm package totals visibly separate,
 - [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) — deterministic, isolated, native, and public-package validation scopes.
 - [`docs/distribution.md`](docs/distribution.md) — verified public distribution destinations and the rename note.
 - [`docs/PRIVACY.md`](docs/PRIVACY.md) — stored facts, prohibited data, and failure behavior.
-- [`docs/UPSTREAM_BASE.md`](docs/UPSTREAM_BASE.md) — semantic baseline and repository authority boundary.
+- [`docs/UPSTREAM_BASE.md`](docs/UPSTREAM_BASE.md) — historical starting point and repository authority boundary.
+- [`docs/SEMANTIC_COMPATIBILITY.md`](docs/SEMANTIC_COMPATIBILITY.md) — current shared behavior and known gaps.
 - [`docs/PORTING_NOTES.md`](docs/PORTING_NOTES.md) — behavior retained from Codex and DSH-specific replacements.
 
 ## Development

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md)
 
-面向 DeepSeek Harness（DSH）的任务合同与完成认证插件。它保存需求、禁止项、验收条件、后续修订和有界证据，只有当前成功证据与当前合同匹配时，任务才能获得完成认证。
+面向 DeepSeek Harness（DSH）的任务保护插件。它保存任务要求，并在任务标记完成前逐项核对；会话恢复后仍使用同一份检查表，只有匹配的已保存工具结果才能作为证据。
 
 ![任务合同条款与有界证据通过 checkpoint 匹配后签发完成证书](assets/social/completion-guard-hero.png)
 
@@ -11,89 +11,74 @@
 将已发布插件安装到 DSH Web profile：
 
 ```sh
-dsh plugin --profile web add dsh-completion-guard@0.3.1
+dsh plugin --profile web add dsh-completion-guard@0.4.0
 ```
 
-重启 DSH Web，打开一个会话并启用 Guard：
+重启 DSH 前，先记录并验证当前 runtime 和 profile。请把示例路径替换为本机绝对路径：
 
-```text
-/context-guard on
-/context-guard status
-```
-
-默认采用 opt-in。`status` 会返回启用状态、当前 epoch 和合同修订、待完成与已通过条目数量、证据数量及完整性状态；`off` 停止本会话的捕获和门禁，但保留已有历史；`clear` 在 `CLEAR:` 哨兵下使所有待完成的 requirement/acceptance 成为 superseded（保留 prohibition），从而让空绑定 checkpoint 也能在 Guard 保持开启的情况下签发证书；`diagnose` 返回有界的诊断信息。
-
-### 启用模式
+```sh
+DSH_RUNTIME_ROOT=/absolute/path/to/.dsh-runtime
+DSH_PROFILE_ROOT=/absolute/path/to/.dsh/profiles/web
+DSH_COMPOSED_DUMP=/tmp/dsh-web-composed.yml
+GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-lock"
 
-`activation` 支持两个值：
+"$GUARD_HOST_LOCK" inspect --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
+"$GUARD_HOST_LOCK" inject --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
+dsh --profile web --dump-config > "$DSH_COMPOSED_DUMP"
+"$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config "$DSH_COMPOSED_DUMP"
+```
 
-| 值 | 行为 |
-| --- | --- |
-| `opt-in` | 默认值。只有本会话记录了 `/context-guard on` 后才开始保护。 |
-| `always` | 在重放会话日志前就进入启用状态。`/context-guard off` 会关闭本会话的 Guard，直到后续再次执行 `/context-guard on`。 |
+Windows 请通过 profile 的 `node_modules\.bin\dsh-completion-guard-host-lock.cmd` 运行相同的三个子命令，并使用 Windows 绝对路径。DSH、profile 或包升级后需要重新检查。如果当前包集合缺失、混装、重复或不属于已检查环境，Guard 会保持不可用。
 
-如需让 Context Guard 在某个 DSH profile 中自动启用，请在该 profile 的 `cordis.patch.yml` 中按插件 ID 增加配置覆盖。macOS 或 Linux 默认 Web profile 的文件通常位于 `~/.dsh/profiles/web/cordis.patch.yml`：
+然后重启 DSH Web，打开会话并启用 Guard：
 
-```yaml
-- id: context-guard
-  name: dsh-completion-guard
-  config:
-    activation: always
+```text
+/context-guard on
+/context-guard status
 ```
 
-修改后重启对应的 DSH profile，再在会话中执行 `/context-guard status`，确认 Guard 已启用。由于 `always` 会在日志重放前启用 Guard，把已有 profile 改为该模式后，已有会话在重建日志时也可能捕获更早的用户消息。如果只希望从明确的逐会话命令开始保护，请保留 `opt-in`。
-
-启用后，Context Guard 从用户直接给出的要求和验收条件建立合同。工具结果只有在 DSH 持久化后才会成为可引用证据。模型在声称整个任务完成前，必须调用注入的 `context_guard_checkpoint` 工具并绑定匹配的证据 ID；不完整、过期或对象不匹配的绑定不能签发证书。
+默认采用 opt-in。`status` 显示 Guard 是否开启以及还有多少检查项。`off` 停止保护当前会话，但不删除历史。`clear` 关闭当前待办，同时保留禁止项。`diagnose` 说明完成检查为什么通过或失败。
 
 ## 它保护什么
 
-- 以稳定 ID 捕获 requirement、acceptance 和 prohibition，并通过 append-only supersession 保存后续修订。
-- 只从 DSH 已持久化的工具调用与结果派生有界、脱敏的证据。
-- 当合同明确指定时，同时匹配方法、操作、对象、surface 和结果状态。
-- 在会话重建或恢复时重新验证证书，完整性丢失时 fail-closed。
-- 启用期间，如果没有当前有效证书，就在 mutation 前阻止 Guard 自己守卫的模型工具 Goal 完成路径；可信进程内直接写 Goal/session 的旁路只检测为 integrity violation，不声称能普遍阻止。
+- 保存需求、验收条件、禁止项和后续修正，不覆盖旧记录。
+- 只使用 DSH 已保存的工具调用和结果，并保存脱敏摘要而不是完整输出。
+- 只有动作和结果对应指定命令、文件或其他目标时，证据才有效。
+- 会话重建或恢复后重新检查完成状态；记录损坏时拒绝签发证书。
+- 当前检查表尚未通过时，阻止 Guard 自己守卫的 Goal 完成路径。DSH 内部仍可能绕过这条路径，因此插件会报告这些情况，不声称能阻止所有写入。
 
 ## 状态与兼容性
 
-0.3.1 是当前 release line。只有 [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) 记录的精确工件公开读回闭合时，其 [npm 包](https://www.npmjs.com/package/dsh-completion-guard) 与 [GitHub Release](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.3.1) 才构成权威发布身份；安装前请核对这些链接身份。
-
-`0.3.0` npm 工件已通过原生平台同字节验收，但由于发布的是预构建 tgz，npm 没有写入合同要求的 `gitHead`。该版本身份不能复用，也不会为 `v0.3.0` 创建 GitHub Release；`0.3.1` 保留其运行时行为并修复发布溯源路径。
-
-> 本项目于 2026-08-29 由 `dsh-context-guard` 更名为 `dsh-completion-guard`,以避免与无关的 DSH 插件(kpl0111/dsh-context-guard,工具结果剪裁)撞名。内部 Cordis bundle id 保持 `context-guard` 不变;原 npm 包 `dsh-context-guard` 将被 deprecate 并指向本包。目标环境为 DSH `0.1.1-rc.2`、Node.js `>=22`、pnpm `>=11`。
-
-### 早期 v0.2.x 证据
+0.4.0 是当前版本，可从 [npm](https://www.npmjs.com/package/dsh-completion-guard) 安装。[GitHub Release](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.4.0) 附有精确的包校验和，以及 macOS、Windows 原生验收记录。它面向 DSH `0.1.2-alpha.3`、dshmarket `1.39.0` 和 Cordis `4.0.2`。
 
-0.2.1 版本测试共 138 项，其中 domain/core 105 项。它会在 shell 工具未提供 `workdir` 时使用会话 cwd 归因证据，支持字面量 `2>&1` 和只读检查命令，把过程动词映射为 run 证据，并在 checkpoint 绑定被拒时提供可执行提示。0.2.1 新增会话层捕获过滤，使澄清提问、元评论和纯推进语（`继续`、`continue`）不再成为合同条目；对重复恢复通知做内容去重；新增 `/context-guard clear`；并文档化在 Guard 关闭或阻塞时 goal 如何完成。macOS 真实 Web 会话已加载公开 profile 包并认证 `pnpm test` 结果。
+0.3.2 继续支持已经检查过的 DSH `0.1.1-rc.2` 和 `0.1.2-alpha.2` 环境。不要混用不同环境的包；只有当前包集合完整匹配 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) 中的一套记录时，Guard 才会启用。
 
-Windows TEMP 读回现已确认 `b75868e9e73d29f50530ddaba15cfaef82e03ece` 的源码矩阵，以及 exact-source tarball → 隔离安装 → dump-config → Web 启动日志与清理链。HTTP 200 只出现在首轮 stdout，未持久化且复核时没有重跑，因此 HTTP 响应本身不能写成“独立复核已确认”。真实模型会话 smoke 仍未运行。
+0.4.0 的兼容基线继续冻结在这套 alpha.3 环境。alpha.4 及此后的 alpha 版本不作为新的适配目标；兼容性适配将在上游发布 alpha.3 之后的第一版 RC 时恢复。上游版本进度见 [DeepSeek Harness 标签页](https://github.com/deepseek-ai/deepseek-harness/tags)。
 
-### v0.3.1
+发布包只从干净提交生成一次；同一份包在 macOS 和 Windows 上完成 Web、Headless 原生检查后才会发布。CI、原生生命周期、包发布和公开读回是四类独立证据，详见 [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md)。
 
-v0.3.1 承载 0.3.0 引入的语义 action/target 绑定、有状态动作独立读回、typed boundary、digest-v3 证书、精确活动宿主身份和成对 optional Goal 集成，并增加确定性 release packer，在原生平台验收与 registry 发布前把完整 Git HEAD 绑定进冻结 tgz。对于未变化的运行时基线，19 个测试文件在 macOS 通过 351 项并按能力跳过 1 项 Windows-only 测试，在原生 Windows 通过全部 352 项且无跳过。[`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) 分别记录源码、工件、CI、模型会话与 publication 证据边界。
+不建议使用 0.3.0。它的包通过了原生检查，但 npm 没有记录所需的源码提交，因此不能原地修复，也没有 GitHub Release。请使用 0.3.2。
 
-该版本使用 [`manifests/action-manifest.v1.json`](manifests/action-manifest.v1.json)、[`manifests/git-command-manifest.v2.json`](manifests/git-command-manifest.v2.json) 与 [`manifests/supported-host.v1.json`](manifests/supported-host.v1.json)。Goal 集成要求精确 optional peers `@deepseek-ai/dsh-goal@0.1.1-rc.2` 和 `@deepseek-ai/dsh-tool-goal@0.1.1-rc.2` 同时存在。活动 DSH runtime/profile graph 未显式注入精确 `hostLockPackages`、platform 与 profile 身份时一律 fail-closed。由于 DSH 核心与 profile 插件使用不同 package graph，运行时不接受“向上找到的最近 lockfile”替代活动宿主身份；默认 bundle patch 也不会伪造这份锁。
+> 本项目于 2026-08-29 由 `dsh-context-guard` 更名为 `dsh-completion-guard`，因为另一个无关插件已经使用旧名称。内部 bundle id 仍为 `context-guard`，旧 npm 包会引导用户使用本包。支持的 DSH 环境见 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md)；需要 Node.js `>=22` 和 pnpm `>=11`。
 
-把该版本安装到 profile 后，使用随包提供的 CLI 生成并回读活动身份。请把下列路径替换为实际 DSH 安装的绝对路径；dump 只是检查产物，不是配置来源：
+## 启用模式
 
-```sh
-DSH_RUNTIME_ROOT=/absolute/path/to/.dsh-runtime
-DSH_PROFILE_ROOT=/absolute/path/to/.dsh/profiles/web
-DSH_COMPOSED_DUMP=/tmp/dsh-web-composed.yml
-GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-lock"
+默认 `opt-in` 模式只在会话执行 `/context-guard on` 后开始保护。如需让某个 DSH profile 自动启用 Guard，请在该 profile 的 `cordis.patch.yml` 中增加：
 
-"$GUARD_HOST_LOCK" inspect --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
-"$GUARD_HOST_LOCK" inject --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
-dsh --profile web --dump-config > "$DSH_COMPOSED_DUMP"
-"$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config "$DSH_COMPOSED_DUMP"
+```yaml
+- id: context-guard
+  name: dsh-completion-guard
+  config:
+    activation: always
 ```
 
-`inspect` 与 `inject` 会拒绝缺失、重复、多版本或漂移的关键包；`verify-dump` 再证明 DSH compose 出的有界 tuple 与活动 graph 读回一致。每次 DSH/profile/package 升级后都应重跑。流程未通过前，证书、依赖 Goal 的完成路径及受影响 action capability 均保持 unavailable。发布验收使用全新隔离 profile，未覆盖用户现有 DSH profile。
+重启 profile 后执行 `/context-guard status`。`always` 会在日志重放前启用 Guard，因此重建已有会话时也可能捕获日志中的早期用户消息。如果只希望从显式命令开始保护，请保留 `opt-in`。
 
-`context_guard_evidence` 只读：负责 target resolution、已持久 effect 验证和独立 state readback。install/apply/restart/publish 以及精确 Git commit/push/pull/fetch mutation 使用单独命名的 `context_guard_action`。resolution 本身不授予 mutation 权限：调用方必须给出精确的 pending 根用户 requirement 及修订、复述已持久 target digest，并逐字段匹配动作所需身份；prohibition 与 acceptance 条目绝不授权 mutation。v0.3 的 package/apply/publish 只接受精确版本授权，Git 授权必须给出 remote 与 canonical 完整 ref/refspec。这些检查在任何 executable、HTTP 请求或 restart intent 之前完成。审批/展示面会在执行前呈现 canonical target 和 command-manifest digest。
+## 如何检查完成状态
 
-Publish target 只接受不含凭证、query、fragment、歧义路径或控制字符的 canonical HTTPS registry base；根合同、npm argv 与 registry readback 冻结同一值。Create/modify resolution 会在 effect 前冻结预期写入后的 digest；modify 还会先把源字节重新散列并与冻结的 pre-digest 比较，再按 pinned、唯一 UTF-8 replacement 语义推导 post-digest，因此 prestate 漂移或不同的实际文件字节都会 fail closed。
+启用后，Guard 会保存用户直接给出的要求和验收条件。只有已保存的工具结果与指定命令、文件或其他目标一致时，才能作为证据。模型在报告整个任务完成前必须通过 Guard 检查；证据缺失、过期或对象不一致时，任务会保持未完成。
 
-Context Guard 只识别一小组可审计的 shell 与 PowerShell 命令。无法支持或存在歧义的语法会保持 incomplete，而不会被部分信任。复合命令、变量、非白名单可执行文件、文件目标重定向和 in-place `sed` 仍不在可认证范围内。精确语法和平台证据见 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md)。
+只读证据收集与修改包、文件、服务或 Git 状态的操作使用不同工具。查询成功不会自动产生变更权限。精确命令限制和平台证据见 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md)。
 
 ## 边界
 
@@ -103,7 +88,11 @@ Context Guard 负责完成认证；Goal、Todo、Compaction、continuation、权
 
 ## 与 Codex Context Guard 的关系
 
-本项目从 [`GreenLv/codex-context-guard`](https://github.com/GreenLv/codex-context-guard) 迁移确定性行为，以 v0.8.8 作为语义基线，但两者服务于不同运行时：
+本项目最初从 [`GreenLv/codex-context-guard`](https://github.com/GreenLv/codex-context-guard) v0.8.8 移植确定性行为。这个版本只是历史起点，不代表当前兼容程度。
+
+双方当前共享到哪里，由固定的兼容性测试数据和差异台账记录。0.3.2 已包含 Codex 0.9.4 系列的 Stop 2.0、digest v3 和共享兼容性测试。0.4.0 又加入了更严格的任务、路径、能力和证明绑定，具体范围见 [`docs/SEMANTIC_COMPATIBILITY.md`](docs/SEMANTIC_COMPATIBILITY.md)；这里描述的是有明确边界的语义对齐，不代表两个产品完全一致。
+
+两个项目服务于不同运行时：
 
 - `codex-context-guard` 是面向 Codex Hook 的 Python 实现，负责 Codex 插件缓存和 Hook 生命周期接入。
 - `dsh-completion-guard` 是独立的 TypeScript 实现，基于 DSH 原生 Session 事件、命令、工具和 Agent 生命周期工作。
@@ -112,9 +101,9 @@ Context Guard 负责完成认证；Goal、Todo、Compaction、continuation、权
 
 ## npm 下载量历史
 
-![dsh-context-guard 与 dsh-completion-guard 的合计累计 npm 下载量增长](https://raw.githubusercontent.com/GreenLv/dsh-completion-guard/stats/npm-downloads.zh-CN.svg)
+![dsh-context-guard 与 dsh-completion-guard 的 npm 累计下载增长](https://raw.githubusercontent.com/GreenLv/dsh-completion-guard/stats/npm-downloads.zh-CN.svg)
 
-该累计图分别展示新旧 npm 包的总量，以竖线标记 2026-08-29 更名，并且只在项目增长曲线中合并两者。npm 下载量统计的是 registry 请求次数，不等于独立用户数或已确认的真实安装人数。工作流每天运行，也支持手动触发。
+累计图分别显示更名前后的 npm 包下载总量，标记 2026-08-29 的更名，并仅在项目增长曲线中合并两者。npm 下载量统计的是 registry 请求，不等于独立用户数或已确认的真实安装人数。工作流每天自动更新，也可以手动触发。
 
 ## 文档
 
@@ -124,7 +113,8 @@ Context Guard 负责完成认证；Goal、Todo、Compaction、continuation、权
 - [`docs/LOCAL_ACCEPTANCE.md`](docs/LOCAL_ACCEPTANCE.md) — 确定性、隔离环境、原生平台和公开包验证范围。
 - [`docs/distribution.md`](docs/distribution.md) — 已验证的公开分发去向与更名说明。
 - [`docs/PRIVACY.md`](docs/PRIVACY.md) — 保存的事实、禁止数据和失败行为。
-- [`docs/UPSTREAM_BASE.md`](docs/UPSTREAM_BASE.md) — 语义基线与仓库权威边界。
+- [`docs/UPSTREAM_BASE.md`](docs/UPSTREAM_BASE.md) — 历史起点与仓库权威边界。
+- [`docs/SEMANTIC_COMPATIBILITY.md`](docs/SEMANTIC_COMPATIBILITY.md) — 当前共享行为和已知差异。
 - [`docs/PORTING_NOTES.md`](docs/PORTING_NOTES.md) — 从 Codex 保留的行为和 DSH 专属替换。
 
 ## 开发