dsh-completion-guard 0.2.1 → 0.3.1

package/docs/ARCHITECTURE.md

@@ -26,7 +26,9 @@ The in-memory `GuardProjection` is a rebuildable cache: `deriveProjection` appli
 
 ## Synchronization
 
-The runtime rebuilds the projection from the log before each step. Before evidence is produced, the runtime awaits `ctx.sessions.flush(session)`; if no durability listener participated, evidence is demoted to `unknown`, which fails closed.
+The runtime rebuilds the projection from the log before each step. Before evidence is produced, the runtime awaits `ctx.sessions.flush(session)`; if no durability listener participated, evidence is marked `durability-unknown`, which fails closed.
+
+The v0.3 runtime accepts host identity only from `hostLockPackages` generated from the active runtime/profile graphs and bound to the active platform/profile kind. It does not infer identity from the nearest `pnpm-lock.yaml`: DSH core and profile plugins have separate locks, and the runtime lock can contain several historical versions. Missing, unreadable, duplicate, multi-version, or drifted identity disables the dependent capability. The audited values and action/platform capability groups live in `manifests/supported-host.v1.json`. `deriveProjection` receives this exact evaluation before it replays any checkpoint, so a certificate is never validated under a default lock and overwritten later; a changed digest retains historical evidence but makes current authority stale. Ordinary persisted `bash`/`pwsh` results are replayed only when the active platform's agent-loop and terminal group is exact; wrong-platform tool names fail closed. Ordinary `read`/`write`/`edit` results require the independent filesystem group, which pins the tool schemas and result/presentation contract together with the local/sandbox provider, observation policy, sandbox policy, and approval services. A filesystem-group failure disables only `create`/`modify` and filesystem-derived facts, not an independently valid terminal action.
 
 Evidence is produced only from persisted `tool/call` + `tool/result` pairs. Guard never inserts context between a Code Mode sub-call and its durable result.
 
@@ -34,9 +36,11 @@ Evidence is produced only from persisted `tool/call` + `tool/result` pairs. Guar
 
 1. `classifyUserInteraction` drops session-layer utterances before capture: bare progression/acknowledgement phrases (`继续`, `continue`), meta questions (`这个收尾具体要做什么`, `是不是bug`), and meta comments/objections. The classifier fails closed — an artifact path, an explicit method, or a non-negated operation verb always keeps the message (or the individual clause inside a mixed message) a captured instruction.
 2. `classifyClause` / `captureClause` classify the remaining direct human message into requirement, acceptance, or prohibition.
-3. `evidenceFromPersistedToolResult` maps a persisted tool result to bounded evidence with capability, subject, and surface, using the tool's structured `meta` and parsed arguments.
-4. `evidenceMatchesItem` requires a verifying capability (filesystem-read, filesystem-edit, web-fetch, deterministic-check) and a matching subject/surface before an enforced item can close.
-5. `certifyCheckpoint` binds evidence to items and emits a certificate bound to epoch, contract revision, and digests.
-6. `goalCompletionDenial` rejects `update_goal(action=complete)` without a current certificate. The gate has no bypass; the documented remediation routes are `/context-guard off` (only after the user confirms the work is done), `/context-guard clear` (supersedes pending requirements/acceptances so a fresh checkpoint can certify), or a truthful `update_goal(action=blocked)`.
-7. `decideTurnStopping` steers a turn that claims whole-task completion without a certificate, capped per turn.
-8. `renderRecoveryPacket` re-injects open requirements after compaction, resume, enable, rejection, or integrity loss. Injection is content-deduplicated: a re-armed packet with unchanged content is injected once, while resume, compaction, an enablement transition, new evidence, or a new contract revision change or forget the digest and always re-remind.
+3. `segmentAuthorityBlocks` keeps quoted/code/reference material outside the contract, supports explicit section adoption, and captures uncertain material fail-closed.
+4. `context_guard_evidence` produces read-only resolution/state facts and validates already persisted effects; `context_guard_action` owns the explicitly mutating install/apply/restart/publish and Git paths. Before any executable, command, HTTP request, or durable intent, the action tool flushes and replays the resolution/contract chain, then runtime authorization binds the action to one exact pending root-owned requirement/revision (never a prohibition or acceptance), rejects any matching pending root prohibition, and rechecks Guard integrity, host identity, semantic action, target-capture status, and every action-specific requested/resolved identity field. Exact package version/profile/registry and explicit Git remote/full refspec are required; resolution-only integrity, boot generation, and Git OIDs remain bound by the target digest and live prestate. `evidenceFromPersistedToolResult` maps persisted results to versioned semantic actions, evidence roles, exact resolved targets, observed state, executable identity, immutable resolution-time expected transition, and bounded diagnostics. Only exact adapter and command-manifest IDs/versions in the shipped manifests may supply structured state facts. On Windows, audited `.cmd`/`.bat` shims are version-probed through a closed invocation whose interpreter is pinned to the canonical `SystemRoot\\System32\\cmd.exe` realpath and version. Resolution and effect bind both identities; execution reuses the revalidated paths and rejects shell-control or expansion characters rather than re-resolving the logical name through `PATH` or trusting a changed `ComSpec`. Modify transition construction first re-hashes the current source bytes against the resolved pre-digest, then applies the pinned unique UTF-8 replacement. Commit readback parses the raw post-commit parent tuple and accepts exactly one parent equal to the resolved pre-effect HEAD; fetch freezes that HEAD and requires the post-effect HEAD to remain identical. Pre-execute revalidation is a correctness gate, not isolation from a concurrently malicious process running as the same user; a mismatching post-action readback remains non-certifiable.
+5. `certifyCheckpoint` flushes and resynchronizes first. Non-stateful actions require an action-compatible minimal facet; every action in the ten-member `STATEFUL_ACTIONS` set requires distinct resolution, effect, and independent state evidence, one shared resolved target, non-overlapping state observations, and an expected-transition predicate frozen and digested by the resolution fact before effect. The binding must reproduce that payload exactly before observed state is compared.
+6. A certificate freezes protocol/certificate versions, epoch, `sessionRefDigest`, `hostLockDigest`, contract revision/hash, explicit null-or-current Goal ref, open/evidence/binding digests, and the final certification digest. The tool computes a candidate without mutating runtime authority; only a persisted tool result that re-derives byte-for-byte becomes current authority.
+7. `goalCompletionDenial` rejects the Guard-owned `update_goal(action=complete)` model-tool path before the Goal mutation unless that certificate is current. A trusted in-process producer can bypass the tool guard; replay detects the durable `goal/change complete` without a certificate and records an integrity violation, but the plugin does not claim to prevent or roll it back.
+8. `context_guard_boundary` persists only qualified `user_wait`, `external_wait`, or `deferred` candidates. After the accepted tool result is flushed and replayed, the post-commit path reads the same active/armed Goal ref, calls `goals.disarm(agent)`, and independently reads the same ref as disarmed. Pre-effect, still-armed, and post-effect-unknown failures have separate fail-closed/fail-loud outcomes.
+9. `decideTurnBoundary` reads only structured Guard/Goal state. Assistant completion prose is diagnostic and never a stop or continuation control source; active/armed continuation belongs to the Goal Round Driver.
+10. `renderRecoveryPacket` re-injects open requirements after compaction, resume, enable, rejection, or integrity loss. Injection is content-deduplicated: a re-armed packet with unchanged content is injected once, while resume, compaction, an enablement transition, new evidence, or a new contract revision change or forget the digest and always re-remind.

package/docs/COMPATIBILITY.md

@@ -17,9 +17,11 @@ The package exposes a named `apply(ctx)` function and a named `inject` array (`[
 
 The plugin accepts an `activation` configuration value of `opt-in` or `always`. The default is `opt-in`; `always` initializes the projection as enabled before the persisted session log is replayed. Invalid values fail during plugin configuration instead of silently falling back. A DSH profile can select `always` with an ID-targeted `config` override in its `cordis.patch.yml`; see the README quick start for the complete example and the replay implications for existing sessions.
 
+Version 0.3 additionally accepts `hostLockPackages`, `hostLockPlatform`, and `hostLockProfile`, generated from the active DSH runtime and profile graphs. Each critical row carries the exact resolved version and registry tarball integrity. Missing, duplicate, multi-version, or drifted identity is not inferred from a nearby lockfile and fails closed. Capabilities are evaluated separately for base/Goal, agent loop, POSIX or Windows terminal, filesystem tools, DSH CLI, plugin inventory, Web control, and jobs; a missing platform- or action-specific group disables only the dependent path. The filesystem group freezes pinned `read`/`write`/`edit` registration, closed result and presentation shapes, the `ctx.fs` local/sandbox implementation, read-before-mutation observation policy, sandbox policy, and approval provider. Consequently a missing or drifted filesystem row disables only `create`/`modify` and ordinary filesystem facts, while a valid terminal or jobs capability remains usable. The audited identity is [`../manifests/supported-host.v1.json`](../manifests/supported-host.v1.json). The packaged `dsh-completion-guard-host-lock inspect|inject|verify-dump` flow in the README is the supported generation and readback path; the default patch has no `hostLockPackages` and therefore fails closed until that flow succeeds.
+
 ## Peer dependencies
 
-Runtime packages are host-provided and declared as peer dependencies: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-agent`, `@deepseek-ai/dsh-commands`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-tools`.
+Runtime packages are host-provided and declared as peer dependencies: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-agent`, `@deepseek-ai/dsh-commands`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-tools`. Goal uses two exact optional peers as one capability: `@deepseek-ai/dsh-goal@0.1.1-rc.2` owns state, and `@deepseek-ai/dsh-tool-goal@0.1.1-rc.2` owns the audited `update_goal` name/schema/arguments. Both graph rows and the live Goal service/tool must agree. Profiles without this complete capability still load, but Goal-dependent integration is inactive. The other peer ranges remain compatible package declarations, while runtime acceptance is constrained by the exact injected host lock.
 
 ## Terminal outcome contract
 
@@ -39,12 +41,20 @@ unsupported or malformed syntax produces no executable or operation facts and
 no certifying subject/capability combination, so it cannot close a contract even
 when the host execution itself succeeded.
 
+Replay also binds the ordinary tool name to the active host surface: `bash`
+requires the exact POSIX terminal group and `pwsh` the exact Windows group.
+The opposite-platform name is `adapter_unavailable`, not a portable alias.
+Likewise, ordinary `read`, `write`, and `edit` results require the exact
+filesystem capability group. Base-lock support alone is insufficient; the
+bounded fact retains an explicit host-capability reason code, carries no
+certifying capability, and has unknown outcome.
+
 ## Verified surfaces
 
 - `dsh --profile web --dump-config` and `--profile headless --dump-config` both include `context-guard`.
 - A real headless boot loads the plugin (apply, `ctx.sessions` access, and listener registration succeed) and only stops at missing provider credentials.
 
-The slash command renders in the Web command directory and its on/off/clear/status/diagnose subcommands produce the expected `command/run`/`command/done`. Version 0.2.1 has 105 domain/core tests and 138 tests overall. The 0.2.0 macOS live acceptance includes a real Web `pnpm test` run with 5 test files and 124 tests passed, followed by a certified checkpoint at contract revision 4; the complete evidence boundary and known gaps are recorded in `LOCAL_ACCEPTANCE.md`. Evidence and certificates are session-scoped: a later DSH session cannot import or certify evidence IDs from an earlier session, so a workflow requiring a certificate must produce its evidence and checkpoint in one session. The published 0.1.0/0.1.1 releases retain separate historical public-package and native-platform evidence. The fail-closed invariants below are asserted as regressions.
+The slash command renders in the Web command directory and its on/off/clear/status/diagnose subcommands produce the expected `command/run`/`command/done`. The v0.3 runtime baseline exercises 352 deterministic tests in 19 files, including all 37 mirrored portable semantic cases and all 29 digest vectors: macOS passed 351 tests with the one Windows-only shim test capability-skipped, while native Windows passed all 352 with no skips. The same canonical pre-release tgz passed isolated Web/Headless install, host-lock inspect/inject/dump/verify, real dshmarket restart readback, HTTP recovery, and cleanup on both native platforms; Headless loaded to the intentional missing-credential boundary. CI covered Ubuntu, macOS, and Windows on Node.js 22 and 24. A credentialed model session verified an accepted evidence binding and persisted typed-boundary/disarm path; an intentionally over-broad prompt remained incomplete and received no false certificate. Version 0.3.1 preserves those runtime bytes and repairs only the frozen-package provenance path after the 0.3.0 registry entry omitted `gitHead`. The final 0.3.1 tgz remains separately bound to native-platform and public registry readback, as recorded in `LOCAL_ACCEPTANCE.md`. Evidence and certificates are session-scoped: a later DSH session cannot import or certify evidence IDs from an earlier session, so a workflow requiring a certificate must produce its evidence and checkpoint in one session. The published 0.1.x and 0.2.x releases retain separate historical evidence. The fail-closed invariants below are asserted as regressions.
 
 ## Session-layer capture filter and goal completion (v0.2.1)
 
@@ -72,7 +82,17 @@ Recovery packet injection is content-deduplicated: an unchanged packet is
 injected once per re-arm, while resume, compaction, an enablement transition,
 new evidence, or a new contract revision always re-remind.
 
-## Certifiable command subset
+## v0.3 semantic action and binding contract
+
+[`../manifests/action-manifest.v1.json`](../manifests/action-manifest.v1.json) freezes the action vocabulary, compatibility matrix, required target/state keys, expected-transition predicates, and accepted structured evidence adapter versions. `generic_run` is not a wildcard and cannot certify another semantic action.
+
+The full `STATEFUL_ACTIONS` set is `install | apply | create | modify | restart | commit | push | publish | pull | fetch`. Each requires distinct resolution/effect/state evidence IDs, exact same-target closure, independent state readback, and a versioned expected-transition payload. An effect-only success is incomplete. Old v0.2 scope-run certificates are retained as `legacy_generic_run` audit facts and do not become current v0.3 authority; unprovable legacy authority is also non-certifiable.
+
+`context_guard_evidence` is a read-only producer for resolution, persisted-effect validation, and state readback. `context_guard_action` is the explicitly mutating surface for exact-tgz install/apply/publish, two-phase dshmarket restart, and exact Git commit/push/pull/fetch. It first flushes and replays the resolution/contract chain, then requires the exact target digest and id/revision of one current pending `root_instruction` or `root_adoption` requirement whose action and complete requested identity match this resolution; a matching pending root prohibition denies the mutation regardless of message order, while prohibitions and acceptance clauses never grant authority. Install/apply require exact package id, version, and profile; publish requires exact artifact id, version, and canonical registry (v0.3 does not authorize `latest` or ranges); push/pull/fetch require repository, remote, and canonical explicit full ref/refspec; restart requires the exact service id. Disabled, integrity-unknown, stale-host, missing, passed, superseded, clarification-required, incomplete-target, action-swapped, target-swapped, and unrebound legacy paths are rejected before executable inspection, command execution, HTTP, or intent persistence. Unknown selector, command-manifest, or Git argument keys are rejected. `install` requires package absence, while `apply` requires an existing package and a changed version/integrity. Publish executes the exact resolved tgz with `--ignore-scripts`; its registry is a canonical HTTPS base shared by capture, argv, and standard packument readback, with credentials, query, fragment, encoded separators, control characters, and ambiguous path segments rejected. Resolution and effect bind the same canonical executable realpath and version. Windows `.cmd`/`.bat` shims additionally bind the canonical `SystemRoot\\System32\\cmd.exe` realpath and version; arguments containing shell-control, expansion, quote, NUL, or newline characters are unsupported, and execution never performs a second `PATH` search or trusts a changed `ComSpec`. Modify re-hashes the source bytes against the frozen pre-digest before deriving the unique UTF-8 replacement post-digest. Restart persists an intent before POST and closes only after a restored process observes a changed boot ID. Git operations reject aliases, implicit/delete/wildcard/force refs, target substitution, and prestate drift. Commit certification additionally rejects root, merge, or substituted-parent commits; fetch certification requires its resolved pre-HEAD, post-HEAD readback, and predicate parameter to be equal. Pre-execute revalidation is a correctness gate rather than isolation from same-user concurrent tampering; any divergent post-action readback is not certified.
+
+Every stateful resolution freezes its expected transition before effect and binds a stable digest of that payload. Checkpoint diagnostics copy this immutable payload from the resolution fact; callers cannot construct create/modify predicates from post-effect state. Create hashes the exact UTF-8 content from the closed write manifest. Modify first reads the original bytes, requires valid UTF-8 and exactly one `old_string` match, applies the pinned single replacement in memory, and hashes the resulting bytes. Restart freezes `health=healthy` as a manifest constant. A later successful effect whose independent state differs from these values remains incomplete.
+
+## Legacy v0.2 command parsing subset
 
 Context Guard v0.2 is **not** a general Bash or PowerShell static analyzer. Only
 the small, auditable grammar below can produce `executable`, `operation` and

package/docs/LOCAL_ACCEPTANCE.md

@@ -1,6 +1,226 @@
 # Local Acceptance
 
-Deterministic checks and an isolated DSH_HOME composition smoke. These establish source correctness and load correctness, not full runtime behavior.
+Each section names its evidence boundary. Deterministic checks, isolated DSH_HOME composition, native-platform lifecycle runs, model sessions, CI, and public release readback are separate claims; none substitutes for another.
+
+## v0.3.1 release-repair gates
+
+Version 0.3.1 preserves the v0.3 runtime and digest behavior while repairing
+the public provenance path. `scripts/release-pack.mjs` requires a clean Git
+root, resolves the full 40-character HEAD, stages the exact npm file set,
+injects that HEAD as `gitHead` only in the staged package manifest, and packs
+the staged package twice. It fails unless both tgz outputs are byte-identical
+and retain the same file count, then emits the single frozen tgz,
+`SHA256SUMS.txt`, and `release-artifact.json`. Publishing must use that tgz
+without repacking. The registry manifest, downloaded registry tgz, annotated
+tag, GitHub Release target, and checksum must all read back to the same commit
+and bytes.
+
+The focused Node test covers exact-HEAD injection, repeated-pack byte identity,
+checksum and artifact-record output, and dirty-tree rejection. Acceptance of
+the final tgz requires the full isolated Web/Headless install, no-op, package parity,
+host-lock, real restart, HTTP recovery, and cleanup lifecycle on native macOS
+and Windows before publication. CI, native-platform evidence, registry
+publication, tag identity, and GitHub Release remain separate gates.
+
+## v0.3.0 incomplete publication (2026-08-31)
+
+Release preparation froze one canonical pre-release package from commit
+`a33b69326eb46fbefc56affc55e2a486695f545c`. The 26-file, 170158-byte tgz
+had SHA-256
+`72d848e313a0e35e06fd1f493215cc0338b86a79a8001a4f07156e782157fe08`.
+The same bytes passed isolated Web and Headless installation, strict second
+no-op, package-file parity, host-lock inspect/inject/dump/verify, plugin load,
+real dshmarket restart, HTTP recovery, process cleanup, and the intentional
+Headless `MISSING_CREDENTIAL` boundary on native macOS and Windows. The
+Windows source run passed all 352 tests without skips; macOS passed 351 with
+the Windows-only command-shim test capability-skipped.
+
+GitHub Actions run 33320743166 passed that exact commit on Ubuntu, macOS, and
+Windows with Node.js 22 and 24. The four mirrored conformance files remained
+byte-identical to their upstream pin, all 37 portable semantic cases ran
+without skips, and all 29 digest-v3 vectors re-derived successfully.
+
+A separate credentialed model-session gate used that exact package. A real
+test result produced an accepted evidence binding with no rejected binding,
+and a persisted typed `user_wait` boundary was accepted; independent
+post-hook observation read back the same Goal as disarmed. An intentionally
+over-broad prompt captured additional non-certifiable clauses, so its
+checkpoint remained incomplete and no completion certificate was issued.
+This proves the bounded evidence, boundary, and disarm paths without claiming
+that arbitrary model instructions are semantically certifiable.
+
+The final documentation-inclusive source was commit
+`12e8411537b7f843aed267bc150a9403ddbb04c9`. Its frozen 26-file,
+171419-byte tgz had SHA-256
+`416b3539d38c13ea0e01b2154f342d911d4c14b81cc90d71f99e8b9bd6d6de45`
+and passed the same isolated lifecycle and same-byte package readback on native
+macOS and Windows. Main CI run 33347875843 and tag CI run 33347976931 passed
+Ubuntu, macOS, and Windows with Node.js 22 and 24. Annotated tag `v0.3.0`
+peels to that commit.
+
+The exact tgz was published as `dsh-completion-guard@0.3.0`; registry shasum
+`4c881b83b6046833229d5f54a062bfa2eea5be6f` and integrity
+`sha512-WSxbxD5N/79SJ/6UW0/XonCUlmckUhMHtj4LhUpa9u3XGC+MFZ/GUX935Y4Aqp8HJmxnj2gdHmAYmk8pcccykg==`
+identify the validated bytes. However, npm did not populate registry
+`gitHead` when publishing the prebuilt tgz. That fails this release's frozen
+public-identity gate. The version and tag remain immutable historical facts,
+but no GitHub Release is created for `v0.3.0`, and 0.3.0 is not claimed as a
+completed release. Version 0.3.1 repairs the packaging path instead of moving
+the tag, reusing the npm version, or weakening the gate after publication.
+
+## Windows exact-source readback (2026-08-30)
+
+Direct readback of the isolated Windows TEMP acceptance evidence verifies
+source commit `b75868e9e73d29f50530ddaba15cfaef82e03ece` (`origin/main` at checkout
+time), tested in a fresh Windows 11 checkout with Windows PowerShell 5.1,
+Python 3.12.10, Node.js 24.18.0, pnpm 11.22.0, and effective
+`core.autocrlf=true`.
+
+The source and conformance matrix is verified:
+
+- `pnpm test` -> 0; 7 test files, 170 tests passed.
+- `pnpm run typecheck` -> 0.
+- `pnpm run lint` -> 0.
+- `pnpm run build` -> 0.
+- `pnpm run pack:check` -> 0.
+- `git diff --check` -> 0.
+- The raw SHA-256 values of all four mirrored conformance fixture files matched
+  their entries in `tests/fixtures/conformance/UPSTREAM_PIN.json`.
+
+The exact-source artifact and load chain is also verified from the TEMP
+clone/log evidence. It used a tarball built from that checkout and a fresh
+isolated `DSH_HOME`:
+
+- All six tracked `dist/` files matched across the HEAD blobs, local build,
+  tarball, and isolated installation.
+- `dsh --profile web --dump-config` read back the `context-guard` bundle, and a
+  Node import smoke loaded the installed package.
+- `dsh --profile web --dump-config`, Web startup logging, process stop, and
+  cleanup completed. An HTTP 200 appeared only in the first-run stdout; that
+  response was not persisted and the readback did not rerun the GET, so HTTP
+  200 itself is not independently confirmed.
+
+With effective `core.autocrlf=true`, the build made all six tracked `dist/`
+paths appear as `M` even though `git hash-object` matched the corresponding
+HEAD blob for 6/6 files and `git diff` contained no content changes. This was
+an EOL status phantom, not an artifact mismatch; `dist/** text eol=lf` now
+pins the generated files to LF while preserving the existing conformance
+fixture LF rule.
+
+Evidence boundary: source checks and the exact-source install/load/startup and
+cleanup chain are verified. A real model-session smoke was not run, and the
+HTTP response lacks independently persisted/read-back evidence. This does not
+establish v0.3 runtime behavior, npm publication, a tag, or a GitHub Release.
+
+## v0.3.0 source candidate gates (2026-08-30)
+
+Source commit `4f079499509822425c80e0b5ab98d1ebc58da9d5` on
+`codex/v0.3.0-sequence-2` passed the deterministic source matrix on macOS and
+native Windows. The commit remains an unpublished source candidate; it is not
+a tag, npm artifact, GitHub Release, or public-package readback.
+
+The macOS source matrix used Node.js 25.1.0 and pnpm 11.22.0:
+
+- `pnpm install --frozen-lockfile` -> 0.
+- `pnpm run typecheck` -> 0.
+- `pnpm test` -> 0; 19 test files, 351 tests passed and the one Windows-only
+  command-shim test was capability-skipped.
+- `pnpm run lint` -> 0 with no warnings.
+- `pnpm run build` -> 0; a second build produced the same generated file names
+  and SHA-256 values.
+- `pnpm run pack:check` -> 0; package identity is
+  `dsh-completion-guard@0.3.0`, and the action, Git command, and supported-host
+  manifests plus the host-lock CLI are included.
+- The portable runner executed all 37 mirrored semantic cases without skips.
+- The DSH digest runner re-derived all 29 digest-v3 vectors; the four mirror
+  file SHA-256 values remain identical to `UPSTREAM_PIN.json`.
+
+The native Windows matrix used a fresh Windows 11 checkout, Windows PowerShell
+5.1, Python 3.12.10, Node.js 24.18.0, pnpm 11.22.0, Git 2.53.0.windows.2, and
+effective `core.autocrlf=true`:
+
+- The focused host-lock/evidence suite passed 33/33 tests with no skips. It
+  executed a `.cmd` shim from a path containing spaces and parentheses, bound
+  both the shim and canonical `SystemRoot\\System32\\cmd.exe` identities,
+  ignored later `PATH`/`ComSpec` substitution, rejected expansion characters,
+  detected a fake `git.cmd` identity swap, and completed the real Git
+  commit/push/fetch/pull round trip within its Windows timeout.
+- `pnpm test` -> 0; all 19 test files and all 352 tests passed with no skips.
+- Typecheck, lint, build, package dry-run, documentation audit, documentation
+  unit tests, `git diff --check`, generated-`dist` parity, and final clean-tree
+  readback passed.
+- All 37 portable semantic cases, all 29 digest-v3 vectors, the four pinned
+  mirror hashes, and cross-repository fixture byte equality passed.
+
+Each platform built and recorded its own local exact-source tarball. The macOS
+artifact SHA-256 is
+`d613d88edbc44ccc020ad48dff6d180e79c04ed5bcabb73d7fae09d449500890`;
+the Windows artifact SHA-256 is
+`397975f720f0c6d734e7faf7279fab3feee1f92433ff457122755d9296adb19f`.
+These raw archive hashes are platform-local build provenance, not a requirement
+that independently packed gzip/tar containers be byte-identical. Both were
+built from a clean checkout of the exact commit, reported the same package
+identity and 26-file package list, retained build-to-`dist` parity, and were
+installed from the artifact that was hashed on that platform. A future release
+must instead freeze one canonical tarball, bind it to the release commit, tag,
+npm `gitHead`, and registry integrity, and verify that same artifact on every
+required native platform.
+
+Both platform-local exact-source artifacts were installed into fresh isolated
+Web and Headless profiles without modifying the user profile. For both
+profiles, the packaged host-lock CLI completed `inspect -> inject -> inject
+(idempotence) -> dsh --dump-config -> verify-dump` against the active
+runtime/profile graphs. The Web tuple contained 34 exact package rows with Web
+control available; the Headless tuple contained 33 rows with Web control
+unavailable by profile while the other applicable capabilities remained
+supported.
+
+On both macOS and Windows, an isolated Web profile loaded real
+`dshmarket@1.36.0`, returned HTTP 200, accepted the correct restart request
+with HTTP 202, replaced the process, and returned a different boot ID after
+restart. The Windows run also verified that a wrong restart origin was rejected.
+Each replacement process returned HTTP 200 before teardown; the temporary
+listener, helper, and profile processes were then read back as stopped. Each
+isolated Headless profile loaded the plugin and advanced to the expected
+`MISSING_CREDENTIAL` boundary with `DEEPSEEK_API_KEY` removed from the child
+environment.
+
+This establishes deterministic source behavior plus native macOS and Windows
+package composition, host-lock readback, load, and Web restart lifecycle for
+commit `4f079499509822425c80e0b5ab98d1ebc58da9d5`. It is not a credentialed
+model-session Goal/checkpoint/boundary round. CI, a canonical release artifact,
+npm/GitHub publication, tag identity, and a real model-session smoke remain
+independent pending release gates.
+
+### npm statistics integration boundary (2026-08-30)
+
+The validation branch later integrated the bilingual npm download chart in
+`131b2db7f7ee555e6e4794395a8aa5118275fa80` and hardened its collector and
+publication workflow in `0ebda88312bf226869543c65de70159fe0abdaca`.
+The collector's 8 focused tests pass on macOS and cover leap-year date chunks,
+missing and unordered days, duplicate/out-of-range/negative rows, range/point
+reconciliation, scoped package URL encoding, HTTP and JSON failures, and
+preservation of the previous output set when collection fails. The fixed-date
+2026-08-29 render reconciled 780 requests for `dsh-context-guard` and 140 for
+`dsh-completion-guard` into a 920-request project line. Both 960 x 540 SVGs
+parsed as XML, retained `<title>` and `<desc>` accessibility text, rendered
+without invalid numeric tokens, and were visually inspected in English and
+Simplified Chinese.
+
+Publication is fail-closed to the repository default branch before checkout.
+The collection job has read-only contents permission and does not retain Git
+credentials; only the downstream publication job receives contents write
+permission. The four official Actions used by the workflow are pinned to
+immutable commits. No `stats` branch or chart asset was published during this
+candidate integration.
+
+Evidence boundary: the runtime source paths, `dist/`, CLI, manifests, and lock
+file remain unchanged from the native-platform candidate above. The chart
+integration does change packaged README and package metadata, and this
+acceptance document is itself shipped in the package. The earlier macOS and
+Windows tarball hashes therefore cannot be inherited by the final candidate.
+One canonical tarball must be built from the final exact commit and the same
+bytes installed and read back on macOS and native Windows before release.
 
 ## macOS v0.2.0 acceptance (2026-08-28)
 

package/docs/SEMANTIC_COMPATIBILITY.md

@@ -0,0 +1,118 @@
+# Semantic Compatibility
+
+`dsh-completion-guard` adapts the Context Guard protocol semantics whose
+canonical owner is `codex-context-guard`. The two products keep separate
+runtimes, persistence, lifecycle, and scheduling; what they share is a
+testable semantic contract tracked by a machine-readable delta ledger and
+byte-mirrored conformance fixtures. This document describes the shared assets
+from the DSH side and their current implementation status. It does not claim
+full feature parity with the Codex product.
+
+## Shared assets in this repository
+
+```text
+docs/upstream-deltas.json
+tests/fixtures/conformance/UPSTREAM_PIN.json
+tests/fixtures/conformance/context_guard_semantics_v1.json
+tests/fixtures/conformance/context_guard_semantics_v1.schema.json
+tests/fixtures/conformance/digest_v3/cases.json
+tests/fixtures/conformance/digest_v3/expected.json
+src/domain/digest.ts
+manifests/action-manifest.v1.json
+manifests/supported-host.v1.json
+```
+
+Authority rules:
+
+- The portable conformance fixture and the digest v3 fixture are canonical in
+  codex-context-guard. This repository holds byte mirrors whose SHA-256
+  values are pinned in `tests/fixtures/conformance/UPSTREAM_PIN.json`; the
+  vitest suite fails when any mirror drifts from its pinned hash.
+- `UPSTREAM_PIN.json` records the upstream head at mirror time, the mirror
+  date, and per-file hashes. The canonical files were created in an upstream
+  working tree pending commit, so `canonicalCommit` is `pending` until the
+  upstream commit that lands them exists; refresh the pin when re-syncing.
+- New protocol cases discovered on the DSH side are turned into
+  platform-neutral fixture cases upstream first; host-specific expectations
+  never enter the shared fixture.
+- `docs/UPSTREAM_BASE.md` records the historical v0.1.0 baseline. It is a
+  historical fact, not a claim that DSH implements Codex protocol versions;
+  current alignment status lives in this document and the delta ledger.
+
+## Digest v3
+
+Certificate, boundary, and evidence manifests bind to versioned canonical
+digests. The derivation contract is frozen as digest version 3 (typed token
+value language, length-prefixed fields with an explicit presence byte,
+semantic-key-ordered canonical collections, closed per-manifest allowlists
+with domain separators). The full contract, the golden-vector gate, and the
+fail-closed edges are documented in the upstream
+`docs/SEMANTIC_COMPATIBILITY.md`; the fixtures are byte mirrors here.
+
+DSH-side facts:
+
+- `src/domain/digest.ts` re-derives the complete digest contract in
+  TypeScript, including the verifier-side role matrix and binding closure.
+- `tests/domain/digest-v3.test.ts` runs all 29 golden vectors from the byte
+  mirror and asserts byte-identical agreement with the upstream-generated
+  `expected.json`, plus the fail-closed negatives (semantic-key sorting, the
+  two collision layers, lone surrogates, NFC vs NFD, duplicate members,
+  camelCase rejection, surface cardinality, frozen length boundaries, and
+  cross-paired evidence rejection).
+- The upstream gate command
+  (`python scripts/reference_digest_encoder.py --check ...`) stays the
+  canonical check; the mirrored fixtures make both implementations answer to
+  the same bytes.
+- Version 0.3 wires the module into checkpoint creation/replay and the
+  Guard-owned Goal-complete gate. Certificates freeze the full versioned field
+  table, including session and host identity, and are authoritative only after
+  the tool result persists and re-derives exactly.
+
+## Portable conformance fixture
+
+`context_guard_semantics_v1.json` holds 37 platform-neutral cases built from the
+event vocabulary `root_message`, `delegated_message`, `tool_result`,
+`checkpoint_request`, `boundary_request`, `completion_request`, `compact`,
+`resume`, and `goal_change`, with bounded expectations (`completed`,
+`completion_allowed`, `force_continue`, `pending_preserved`, `boundary`,
+`integrity`, `reason_codes`). All content is synthetic. The DSH-side portable
+runner executes every mirrored case without skips and compares the bounded
+result contract; it does not translate a missing capability into a pass.
+
+## Current alignment status (honest boundaries)
+
+Implemented in v0.3.0:
+
+- Digest v3 derivation, byte-mirror pinning, and 29-vector agreement.
+- All-case portable semantic fixture runner implemented as a thin adapter over production derive/checkpoint/boundary/Goal/stop functions, without fixture-ID rewrites or skipped cases.
+- Assistant-prose diagnostic-only stop decisions and typed boundary
+  qualification/effectuation with phase-specific fault results.
+- Exact semantic action/target binding, explainable checkpoint rejection, and
+  resolution/effect/state role closure for all ten stateful actions.
+- Exact paired optional Goal state/tool peers, supported-host/action manifests, injected active
+  graph identity, unknown-host fail-closed behavior, and pre-mutation gating of
+  the Guard-owned `update_goal(action=complete)` path.
+- Legacy generic-run and unprovable-authority fail-closed migration behavior.
+
+This is not a full product-parity claim. It does not copy the Codex private
+ledger, Hook lifecycle, cache, or installer, and it cannot prevent all trusted
+in-process Goal/session bypasses. Exact-artifact isolated Web/Headless install,
+host-lock readback, Web restart lifecycle, and Headless load were exercised on
+native macOS and Windows, with cross-platform CI and a bounded credentialed
+model-session evidence/boundary round. Source, native-platform, model-session,
+registry, tag, and GitHub Release evidence remain separate scopes; see
+`LOCAL_ACCEPTANCE.md`.
+
+## Validation boundaries
+
+- `pnpm install --frozen-lockfile && pnpm typecheck && pnpm test && pnpm
+  lint && pnpm build` covers deterministic tests and build health on this
+  machine. That is not native platform acceptance: Web/Headless profile load,
+  real checkpoint/boundary/Goal round flows, and macOS/Windows native
+  acceptance are separate records and are not claimed here.
+- Deterministic test evidence never substitutes for npm/GitHub Release
+  identity readback or the identity migration gates recorded in the plan for
+  the v0.3.0 release.
+- The delta ledger separates source facts, plan status, implementation
+  status, deterministic tests, native platform acceptance, and release
+  readback; keep all six aligned when a capability moves.

package/docs/distribution.md

@@ -0,0 +1,54 @@
+# Distribution status
+
+This page records where `dsh-completion-guard` is published and independently
+read back. Only verified, publicly live destinations are listed here; the
+private submission pipeline and in-review entries are tracked outside the
+repository and are intentionally not disclosed.
+
+## Rename note (2026-08-29)
+
+The project was renamed from `dsh-context-guard` to `dsh-completion-guard` to
+avoid a name collision with an unrelated DeepSeek Harness plugin
+(`kpl0111/dsh-context-guard`, a token-efficient tool-result pruning plugin
+created 2026-08-16). The internal Cordis bundle id stays `context-guard`, so
+installed profiles keep their runtime identity. The previous npm package
+`dsh-context-guard` is deprecated across all published versions (0.1.0 –
+0.2.1) with a pointer to this package.
+
+## Incomplete v0.3.0 identity
+
+`dsh-completion-guard@0.3.0` is publicly readable from npm and its tarball
+passed same-byte native macOS and Windows validation. The registry metadata
+omits the release contract's required `gitHead`, however, so `v0.3.0` is not
+listed as a completed destination and has no GitHub Release. The immutable npm
+version and annotated tag are retained for audit history. Version 0.3.1 repairs
+the provenance-bearing frozen-package workflow.
+
+## Published v0.2.1 destinations
+
+1. [GitHub Release `v0.2.1`](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.2.1)
+   is published as a non-draft, non-prerelease release; the repository was
+   renamed after tagging and the release URL follows the rename (old URLs
+   301-redirect). The tag points at commit `ba8f05d`; the published npm
+   artifact was built from `8497300`, whose dist is byte-identical to the
+   gate build.
+2. [`dsh-completion-guard@0.2.1` on npm](https://www.npmjs.com/package/dsh-completion-guard)
+   is published and `latest` resolves to `0.2.1`. The registry packument
+   `gitHead` equals the rename commit `8497300`, maintainer `greenlv`.
+3. The committed `dist/` tree is byte-identical to the published npm tarball
+   (verified 2026-08-29 by diffing the registry tarball against the local
+   build; only `.DS_Store` is excluded and git-ignored).
+
+## Community indexes
+
+| Channel | Entry | Status | Evidence |
+|---|---|---|---|
+| [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) | `GreenLv/dsh-completion-guard` (category `security`) | Listed | Added via [PR #3693](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/3693) (merge commit `299f0b5c`, 2026-08-29); read back live the same day from the generated `README.md` (line 2469, security-category section) and `README.zh.md`, the committed `data/plugins/GreenLv__dsh-completion-guard.yml`, and the published catalog at [`awesome-dsh-plugin.com/plugins.json`](https://awesome-dsh-plugin.com/plugins.json), which exposes the storefront page [`awesome-dsh-plugin.com/p/GreenLv/dsh-completion-guard/`](https://awesome-dsh-plugin.com/p/GreenLv/dsh-completion-guard/). Screenshots: declared in this repository's [`screenshots.json`](../screenshots.json) per the maintainer's post-#2937 convention (change images by pushing here; no listing PR needed). |
+| [Awesome DeepSeek Harness](https://github.com/Dominic789654/awesome-deepseek-harness#security--permissions) | `GreenLv/dsh-completion-guard` | Listed | Rows merged via [PR #332](https://github.com/Dominic789654/awesome-deepseek-harness/pull/332) (merge commit `ba414c4`, 2026-08-29) and read back live the same day from both generated READMEs (`README.md` line 940, `README.zh-CN.md` line 946), under **Security & Permissions** alongside the other fail-closed gates and verifier plugins. |
+
+## Update route
+
+Directory entries resolve the npm `latest` tag or link the repository, so
+routine releases refresh automatically. Row wording changes go through a pull
+request against the listing repository. Historical acceptance evidence for
+each release is kept in [`docs/LOCAL_ACCEPTANCE.md`](LOCAL_ACCEPTANCE.md).