dsh-completion-guard 0.2.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# Architecture
+
+Context Guard separates DSH-owned execution from Guard-owned certification.
+
+## Responsibility boundary
+
+| Module | Owns |
+| --- | --- |
+| DSH Goal | Persisted objective, automatic goal rounds, pause/resume/block/complete |
+| DSH Todo | Lightweight current plan display |
+| DSH Compaction | Model-visible history reduction without corrupting tool-call structure |
+| Context Guard | Per-item task contract, revisions, evidence binding, and completion certificate |
+
+Context Guard does not own Goal, Todo, Compaction, or continuation. It intervenes when completion is claimed without a valid certificate.
+
+## Durable state model
+
+The effective plugin configuration and the DSH Session append-only log are the inputs to the rebuildable Guard projection. Context Guard **appends no custom session event types**: the persisted event vocabulary is harness-owned and the current persistence layer refuses unknown event types. The `activation` configuration supplies the initial enablement state, while all later session state is derived from the natively persisted events DSH already writes:
+
+- effective plugin configuration — initial enablement (`opt-in` starts disabled; `always` starts enabled before log replay);
+- `command/run` — later enablement (`/context-guard on|off|clear`) and epoch transitions;
+- `user/message` — captured contract clauses;
+- `tool/call` + `tool/result` — bounded evidence and completion-certificate attempts.
+
+The in-memory `GuardProjection` is a rebuildable cache: `deriveProjection` applies the effective activation configuration, replays the native log deterministically, recomputes every contract, evidence, and certificate, and flags `corrupt` when a recorded certificate no longer re-derives from the evidence in the log. The projection and its evidence are session-scoped: a new DSH session starts a new projection and cannot import, look up, or certify evidence IDs from another session. A completed workflow that needs a certificate must therefore produce its evidence and call `context_guard_checkpoint` in the same session. Under `always`, replay begins enabled; changing an existing profile from `opt-in` to `always` can therefore bring earlier persisted user messages into the derived contract. A recorded `/context-guard off` disables capture from that point until a later `on`. A recorded `/context-guard clear` supersedes every pending requirement and acceptance under a `CLEAR:<revision>` sentinel (prohibitions are retained) and bumps the contract revision, so a fresh empty-binding checkpoint can certify while the guard stays enabled. Captured contracts always carry a concrete subject/surface, so no unrelated evidence can close a requirement.
+
+## 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.
+
+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.
+
+## Domain pipeline
+
+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.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,169 @@
+# Compatibility
+
+The current development target is pinned, not a floating claim.
+
+## Target
+
+- DeepSeek Harness: `0.1.1-rc.2`
+- Cordis: `4.0.1`
+- Node: `>= 22`
+- pnpm: `>= 11`
+
+The DSH host is a developer preview that declares breaking changes. A source build does not establish native acceptance; each profile and platform is verified separately.
+
+## Loader contract
+
+The package exposes a named `apply(ctx)` function and a named `inject` array (`['sessions', 'commands']`) with no default export. Its `dsh.bundle.patch` points at `cordis.patch.yml`, which inserts the `context-guard` bundle row.
+
+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.
+
+## 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`.
+
+## Terminal outcome contract
+
+The pinned DSH `bash` and `pwsh` renderers append terminal markers for sandbox
+denial, timeout, signal termination, and non-zero exit. A completed foreground
+result with none of those markers is the renderer's representation of a clean
+exit; it does not append `[exit code: 0]`. Version 0.1.1 therefore accepts an
+unmarked completed foreground `bash` result as successful evidence, matching the
+existing `pwsh` behavior.
+
+This does not make arbitrary shell text authoritative. A result-level error or
+negative terminal marker wins over output text; background commands remain
+unknown; and the generic `shell` alias remains unknown without an explicit exit
+marker because no pinned host renderer contract has been verified for it.
+Outcome classification also remains separate from command certification:
+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.
+
+## 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.
+
+## Session-layer capture filter and goal completion (v0.2.1)
+
+Not every direct user message becomes a contract item. Informational reports
+(receipts, pasted summaries) were already excluded; v0.2.1 additionally drops
+session-layer utterances: bare progression/acknowledgement phrases (`继续`,
+`好的`, `continue`), meta questions (`这个收尾具体要做什么`, `是不是bug`),
+and meta comments or objections without a task feature. The filter also runs
+per clause, so a conversational opener inside an otherwise actionable message
+(`好的。请修改 src/a.ts`) no longer adds a phantom scope requirement. The
+classifier fails closed: an artifact path, an explicit method, or a
+non-negated operation verb always keeps the message captured, and uncertain
+phrasing stays a captured requirement. Old sessions replay unchanged — a
+contract already polluted by such messages remains historical state and is
+remediated explicitly (below), not by re-derivation.
+
+`update_goal(action=complete)` stays denied while the guard is enabled without
+a current completion certificate. The remediation routes are explicit:
+`/context-guard off` disables gating (use only after the user confirms the
+work is actually done), `/context-guard clear` supersedes pending
+requirements/acceptances under a `CLEAR:<revision>` sentinel (prohibitions are
+retained) so an empty-binding checkpoint can certify while the guard stays
+enabled, and `update_goal(action=blocked)` records the blocker truthfully.
+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
+
+Context Guard v0.2 is **not** a general Bash or PowerShell static analyzer. Only
+the small, auditable grammar below can produce `executable`, `operation` and
+`subject`; any other command parses as `unsupported` (unterminated quotes parse
+as `malformed`) with EMPTY executables and operations, so unrecognized syntax
+can never certify an operation. False negatives are preferred over false
+positives: an uncertain command keeps its item incomplete.
+
+The enumerations that define this surface (tools, executables, clause verbs)
+are declared once in `src/domain/manifest.ts`; the parsers and the contract
+capture read from that single data source, which test-time validation keeps
+non-empty and duplicate-free with the documented verb priority order. The
+manifest ships with the package and is not runtime-writable: widening the
+surface lowers the evidence bar, so it changes only through a release.
+
+### Supported POSIX shell (single foreground simple command)
+
+- `printf … > literal-path`
+- `echo … > literal-path`
+- `touch literal-path`
+- read-only inspection tools (`cat`, `grep`, `rg`, `head`, `tail`, `wc`,
+  `sed` without in-place flags): every pathish argument counts as a read effect
+  (v0.2)
+- one whitelisted executable run directly, e.g. `node script.js`,
+  `python tool.py`, `pnpm test`, `git pull`,
+  `dsh plugin --profile web add dsh-dream-skin@0.3.1`
+- a leading simple environment-assignment prefix, e.g. `CI=1 pnpm test`
+  (wrappers such as `env`, `nohup`, `time`, `command` are not supported)
+- diagnostic stream duplication (`2>&1`, `1>&2`, `N>&M`) in any position
+  (v0.2); it is a pure fd copy with no filesystem effect
+
+Literal paths only: no variables, globs, `~` expansion or command substitution.
+
+### Unsupported → fail-closed (whole command, no partial results)
+
+- unquoted LF/CRLF command boundaries, `;`, `&&`, `||`, pipelines (`|`), background (`&`), parentheses/subshells
+- `$(…)`, backtick command substitution, heredoc/here-string (`<<`, `<<<`)
+- unterminated quotes, dynamic `eval`/`source`/`.`-sourcing
+- non-literal (variable/glob) redirect targets or arguments
+- `>>`, `<`, file-target fd redirects (`2>`, `2>>`) and all other redirections
+  beyond a single `>` or an `N>&M` stream copy
+- in-place `sed -i`/`sed --in-place` editing
+- executables outside the v0.2 whitelist
+
+### Supported PowerShell (single directly invoked command)
+
+- the v0.1 cmdlet set: `Set-Content`, `Add-Content`, `New-Item`, `Out-File`,
+  `Get-Content` with the exact documented parameters
+- v0.2: a whitelisted external executable (`git`, `pnpm`, `npm`, `node`,
+  `python`, `tsc`, `vitest`, `pytest`, … – the same run-executable set as the
+  POSIX side) invoked directly with all-literal arguments, e.g.
+  `git push origin main`, `pnpm add pkg@1.0.0`; its run effect carries the
+  first pathish argument
+- v0.2: unquoted `N>&M` stream duplication is stripped everywhere (a quoted
+  `"2>&1"` remains an ordinary value)
+
+Requirements: the command must be unquoted at the command position; the path
+must come from the explicit named path parameter (cmdlets) or be a literal
+argument (external executables); a quoted path is one token (spaces allowed);
+permitted value parameters (`-Value`, `-Encoding`, and `-ItemType`
+where listed above) never contribute subjects;
+`-WhatIf` and `-Confirm` are unsupported because they can avoid or defer the
+claimed effect; positional paths, variables, expressions, `Join-Path`,
+subexpressions, pipelines, `;`, script blocks, `&`, dot sourcing, `Copy-Item`,
+`Move-Item`, `Rename-Item` and `.NET WriteAllText` are unsupported and fail the
+WHOLE command.
+
+### Subject resolution (v0.2)
+
+Evidence artifact subjects are resolved against the call's `workdir`; when the
+shell tool carries none (the macOS persistent bash/pwsh tools expose only
+`command`), the session scope cwd is used as the default, so relative paths and
+scope-run attribution match the contract subject derived from the same cwd. A
+pathless `run` operation of a whitelisted executable is attributed to that cwd,
+which is what closes a scope `run` contract; builtins (`echo`, `cat`, …) never
+become a subject-carrying run.
+
+### Binding invariants
+
+- `run`: the successful method evidence (method + operation + subject) alone
+  closes the contract; no extra read or unrelated deterministic-check is needed.
+- `create`/`write`/`modify`: require one successful effect evidence matching
+  operation and subject, plus an independent successful state-verification
+  evidence on the same subject. When an explicit method is present, that method
+  identity must be carried by the effect evidence itself; without an explicit
+  method, any compatible effect evidence may satisfy the effect facet.
+- `read`: a successful read evidence matching method, read operation and
+  subject satisfies the method side and the object side at once.
+- `verify`: one evidence must simultaneously provide success, an explicit
+  read/verify/deterministic-check capability, the canonical subject and surface,
+  and any required method identity; separate method and verification evidence
+  cannot be spliced together.
+- an explicit method whose operation cannot be parsed fails closed.
+- prohibitions keep their existing semantics.

package/docs/LOCAL_ACCEPTANCE.md

@@ -0,0 +1,337 @@
+# Local Acceptance
+
+Deterministic checks and an isolated DSH_HOME composition smoke. These establish source correctness and load correctness, not full runtime behavior.
+
+## macOS v0.2.0 acceptance (2026-08-28)
+
+Verified source commit: `c107cd8ead97988f6a71cab8182edb16b23b086b`, on `main`, with a clean worktree and `main == origin/main` at the release preflight. Node v25.1.0 and pnpm 11.22.0 were used on macOS.
+
+Repository gates passed before publication:
+
+- `pnpm install --frozen-lockfile` -> 0.
+- `pnpm test` -> 0; 5 test files, 124 tests passed.
+- `pnpm run typecheck` -> 0.
+- `pnpm run lint` -> 0 errors / 0 warnings.
+- `pnpm run build` -> 0.
+- `pnpm run pack:check` -> 0.
+- `validateManifest()` returned no errors. The semantic checks covered informational receipt filtering, deterministic-check classification, `2>&1` support, and rejection of compound `&&` syntax.
+
+Live Web acceptance after installing `dsh-context-guard@0.2.0` into the managed `web` profile and restarting DSH:
+
+- The live profile reads installed version `0.2.0`; `dsh --profile web --dump-config` includes the `context-guard` bundle.
+- A real Web session in this repository executed one foreground Bash `pnpm test` call. The persisted result reported 5 test files and 124 tests passed.
+- The next checkpoint bound the successful evidence (`E0001`) to the two current session items. The checkpoint returned `status: certified`, `contract_revision: 4`, with `rejected_bindings: []` and `open_items: []`.
+
+Publication and consumer readback:
+
+- `npm view dsh-context-guard dist-tags.latest` -> `0.2.0`.
+- npm `gitHead` for `0.2.0` -> `c107cd8ead97988f6a71cab8182edb16b23b086b`.
+- The official `dsh-context-guard-0.2.0.tgz` unpacks to version `0.2.0`; all six packaged `dist/` files are byte-identical to the local build by md5. The local-only `dist/.DS_Store` is not part of the npm package and is excluded from this comparison.
+- Annotated tag `v0.2.0` was pushed. Remote readback returned tag object `dc1b13e00b2e1adadacb2c8de0a533ec8f51ac22` peeling to commit `c107cd8ead97988f6a71cab8182edb16b23b086b`.
+- codex-sync update discovery reported exactly `dsh-context-guard 0.1.2 -> 0.2.0`; the dry run planned one update, apply succeeded, the installed profile package reads `0.2.0`, the bundle contains `context-guard`, and the follow-up dry run returned `No DSH plugin changes needed`.
+
+Evidence boundaries:
+
+- The live 0.2.0 checkpoint certifies the real `pnpm test` workflow and its bound session items. It does not certify every release requirement in the recovered handoff contract.
+- The rejected compound-command case with an actionable `rejected_bindings[].hint`, and informational receipt filtering, are covered by the 0.2.0 semantic/regression checks and earlier real-session evidence; they were not re-created as additional live Web calls in this acceptance run.
+- Windows native acceptance remains the documented 0.1.x bounded PowerShell result; no Windows 0.2.0 run is claimed here.
+
+## macOS v0.2.1 acceptance (2026-08-28)
+
+Verified source commit: `ba8f05dc6a922b8a12f4dc211d9a888d2ece526a` (= annotated tag
+`v0.2.1`, tag object `5bccac9dd77549a929137befd808dc1701d77093`). Repository gates
+and package verification ran on a clean worktree at that commit; the npm
+publication ran from `806aa863234a064b5c42391fa1288998abfc846e` as recorded
+below. Node v25.1.0, pnpm 11.22.0, npm 11.17.0 on macOS 26.6.2 (arm64). The
+pre-publish artifact `dsh-context-guard-0.2.1.tgz` had SHA-256
+`ea2b6a0bc1db82150af9d88494b6c9d2a1e0243d33ed21df48d3c23d7c52a895`.
+
+Repository gates passed at `ba8f05d` (each exit code recorded at run time; the
+untracked `docs/PROBLEM_REPORT_v0.2.1.md` was moved out of the worktree for the
+pack steps and restored afterwards):
+
+- `pnpm install --frozen-lockfile` -> 0.
+- `pnpm run typecheck` -> 0.
+- `pnpm test` -> 0; 6 test files, 138 tests passed (`tests/domain/conversation.test.ts`
+  is the new v0.2.1 conversational-capture matrix with 7 tests).
+- `pnpm run lint` -> 0; 0 warnings / 0 errors (26 files, 96 rules).
+- `pnpm run build` -> 0; 6 files, 151.33 kB total.
+- `pnpm run pack:check` -> 0; `dsh-context-guard-0.2.1.tgz`, 19 files, and the
+  untracked problem report is not part of the package.
+
+Installed-state verification: the tgz above was added to the real `web` profile
+(`dsh plugin --profile web add file:...`) and to the `headless` profile; both
+installed packages read `0.2.1`, `dsh --profile web --dump-config` still composes
+the `context-guard` bundle, and DSH web was restarted after the install (new
+process PID 97136 started 09:55, listening on 127.0.0.1:3080, after the 09:53
+install) so the live instance loads 0.2.1.
+
+### Live multi-turn Web session (one guarded session, all steps)
+
+A brand-new guarded session in the real Web UI (workspace `dsh-context-guard`,
+DeepSeek-V4-Flash-Vision-Exp, workspace-write), driven through a dedicated
+Chrome instance over the Chrome DevTools Protocol — the same browser-automation
+lane this DSH install uses for its own browser skill (`chrome-devtools-mcp`).
+User messages were submitted with CDP-trusted pointer events on the composer's
+send control; every acceptance observable below was double-checked against the
+server-side session log
+(`~/.dsh/sessions/…/session-6dcd1274-d4bb-430f-a07c-bcddda8a3bca/session.jsonl.zstd`).
+The profile's managed patch layer already sets `context-guard` to
+`activation: always`, so the session was guarded from its first event.
+
+1. Baseline: `/context-guard status` -> `{"enabled":true,"epoch":0,
+   "contract_revision":0,"pending":0,"passed":0,"evidence":0,
+   "integrity":"valid"}`.
+2. Change 1, clarifying message: `这个收尾具体要做什么` was sent; the model
+   answered (and explored the repository, producing 32 evidence entries). The
+   next `/context-guard status` returned `pending:0`, `contract_revision:0` —
+   the clarifying question was not captured as a contract item.
+3. Change 1, progression phrase: `继续` was sent; the model continued its
+   analysis. `/context-guard status` again returned `pending:0` (evidence 37) —
+   the progression phrase was not captured.
+4. Evidence production and certified checkpoint: the single-clause task
+   "在本仓库前台单一命令运行 pnpm test 且不得使用管道分号或重定向，然后用本次运行产生
+   的证据调用 context_guard_checkpoint 绑定全部开放项完成认证" was captured as
+   `R001` (checkpoint with empty bindings returned `incomplete`,
+   `open_items:["R001"]`); the model executed a clean foreground `pnpm test`
+   (single command, no pipes or redirects; 6 files / 138 tests passed), which
+   produced durable evidence `E0038` (bash, scope, outcome success, shell +
+   deterministic-check), and the binding `{"item_id":"R001",
+   "evidence_ids":["E0038"]}` returned `{"status":"certified",
+   "contract_revision":1,"open_items":[],"rejected_bindings":[]}`. Both raw
+   tool results are persisted in the session log.
+5. Pre-clear goal-gate denial (fail-closed evidence): a verification message
+   was itself captured as `R002` (revision 1 -> 2); the model's empty-binding
+   checkpoint returned `incomplete, open_items:["R002"]`, and
+   `update_goal(action=complete)` was denied with "Context Guard requires a
+   current completion certificate before Goal completion." — the gate denies
+   before checking whether a goal exists (`get_goal` returned `{"goal":null}`).
+6. Clear remediation: `/context-guard clear` returned "Context Guard contract
+   cleared: 1 requirement/acceptance item(s) superseded; 0 pending remain
+   (prohibitions retained)." A follow-up verification (phrased as a question,
+   which the conversational filter does not capture) re-ran both tools:
+   the empty-binding checkpoint returned `{"status":"certified",
+   "contract_revision":8,"open_items":[],"rejected_bindings":[]}`, and
+   `update_goal(action=complete)` was no longer blocked by the guard — it
+   reached the goal tool's own argument validation (`goal_id` placeholder
+   rejected) because this session has no active goal. The final
+   `/context-guard status` read `{"enabled":true,"epoch":0,
+   "contract_revision":8,"pending":0,"passed":1,"evidence":43,
+   "integrity":"valid"}` — the guard stayed enabled across the clear.
+
+Headless cross-checks (fresh guarded session per run, `--patch` overlay with
+`activation: always`, real model turns; server logs under `~/.dsh/sessions/`):
+
+- Compound-command rejection: `pnpm test 2>&1 | tee …; echo …` produced
+  scope-only evidence and the binding attempt was rejected with `incomplete`
+  and per-item hints ("needs a scope run effect: a whitelisted executable …
+  without pipes, `;` or `&&`"). No binding rule was changed for it.
+- Recovery-injection dedup: across three headless sessions, six
+  `context_guard_checkpoint` rejections (nonexistent evidence `E9999`, both
+  missing-item and evidence-mismatch reasons) produced exactly one
+  "Open task requirements (recovered after compaction or resume):" plugin
+  notice per session — no duplicate recovery packet was ever injected live.
+  The step-separated identical-rejection scenario is covered deterministically
+  by `tests/runtime.test.ts` ("recovery injection dedup (v0.2.1)").
+
+Evidence boundaries:
+
+- The live Web session covers the work order's steps 1-5 (status baseline,
+  clarifying message, progression phrase, supported-task evidence with a
+  certified checkpoint, and clear -> empty-binding certified -> goal-gate
+  release with the guard still enabled). The `update_goal` leg ends at the
+  goal tool's own argument validation because the acceptance session had no
+  active goal; the gate's release is nonetheless demonstrated, and the denial
+  path was captured live pre-clear.
+- Evidence remains session-scoped by design; cross-session evidence IDs are
+  rejected and no cross-session import exists. Windows native behavior is not
+  re-claimed here; the 0.2.0 Windows records stand.
+
+### Publication and consumer readback
+
+The npm publication was authorized and executed from
+`806aa863234a064b5c42391fa1288998abfc846e` ("docs: update READMEs to v0.2.1"),
+a post-release README follow-up commit that was already on local `main` (not
+pushed at the time) when the release was approved. Per the maintainer's
+explicit choice, the registry `gitHead` therefore points at `806aa86…` rather
+than the tag commit `ba8f05d…`; the annotated tag `v0.2.1` itself was not
+moved and still peels to `ba8f05d…`.
+
+- `npm publish` -> `+ dsh-context-guard@0.2.1` (19 files, package size
+  70.5 kB, shasum `2a32ce46fd00fd87d144011653bd99fe2c5a9bd5`). The account's
+  npm token had expired and the publish required npm's EOTP web
+  authentication, completed in the browser.
+- `npm view dsh-context-guard dist-tags.latest` -> `0.2.1`; versions sequence
+  `0.1.2, 0.2.0, 0.2.1`.
+- `npm view dsh-context-guard@0.2.1 gitHead` -> `806aa863234a064b5c42391fa1288998abfc846e`.
+- The official `dsh-context-guard-0.2.1.tgz` unpacks to version `0.2.1`; all
+  six packaged `dist/` files are byte-identical (md5) to the `ba8f05d`
+  gate-run build, and both README files are byte-identical to the `806aa86`
+  content. No `docs/PROBLEM_REPORT_v0.2.1.md` is part of the package.
+
+## 0.1.1 release candidate (2026-08-27)
+
+The candidate was built on macOS from branch
+`codex/0.1.1-bash-success-evidence`. The tested runtime domain bundle is
+`dist/domain-DEXOzCqH.js` with SHA-256
+`e8ad974b8263a2a25c7ef08ca3839097d3312c10d450b8520163c623e54881f9`.
+The exact pre-commit source-tree and tgz digests are recorded in the generated
+candidate manifest rather than embedded here: this document is itself part of
+the npm archive, so embedding that archive's digest would change the digest.
+
+Verified for this candidate:
+
+- `pnpm install --frozen-lockfile`, typecheck, lint, all 106 tests, build, and
+  package-content validation completed successfully on macOS.
+- The candidate tgz composed into fresh isolated `web` and `headless` profiles.
+  Both installed packages read back as `0.1.1`; a second identical add reported
+  `Already up to date`, and hashes of the profile manifests, lockfile, composed
+  patch files, and installed package manifest did not change.
+- The 0.1.1 domain runtime replayed a completed real DSH Web log captured with
+  `activation: always` and confirmed durability. Its foreground `bash`
+  `pnpm typecheck` result contained ordinary stderr output and no
+  `[exit code: 0]` marker; replay derived successful scope evidence and issued a
+  certificate for all four matching open items with no rejected bindings.
+- A clean Windows checkout of commit
+  `16ea9e7a5d088ce6b7e09617f15acd771f57ff40` passed the frozen install,
+  typecheck, lint, all 106 tests, build, and package-content validation with
+  DSH `0.1.1-rc.2`. The candidate package was
+  `dsh-context-guard@0.1.1` with SHA-256
+  `6c0aed77a9fc7f43f6d8bc11e4355d465d1146c81fe10276ad3e523f0abd8a83`.
+  Fresh isolated Web and headless profiles both read back version `0.1.1`; a
+  second identical installation was a strict no-op with unchanged lockfile
+  hashes.
+- A separate minimal Windows real-model session loaded that candidate with
+  `activation: always`. One supported foreground `pwsh Set-Content
+  -LiteralPath ... -Encoding ascii -NoNewline` call created
+  `D:\dsh-pwsh-acceptance\pwsh-acceptance.txt`, and an independent `read`
+  returned `guard-test`. The persisted create evidence and read evidence were
+  bound to the single current contract; the checkpoint returned `certified`
+  at contract revision 1 with no open items or rejected bindings.
+
+Evidence boundary:
+
+- The macOS Web result is a candidate-runtime replay of a genuine closed Web
+  log, combined with isolated Web composition. It is not a claim that the
+  unpublished candidate was installed into the user's live Web profile.
+- The Windows certificate covers only the documented PowerShell subset and the
+  exact candidate identity above. The first workspace-confined write attempt
+  was rejected because the target was outside the checkout; the same single
+  command succeeded only after an explicitly approved elevated retry. The
+  rejected call was not available for certification. This run does not expand
+  the Windows Bash claim or certify compound PowerShell commands.
+- An earlier Windows session completed its model turn without a certificate,
+  and a later diagnostic session produced only scope evidence for compound
+  PowerShell calls. Neither is counted as acceptance. The successful result is
+  the fresh revision-1 session whose supported write and independent read
+  produced artifact-matching evidence.
+- These pre-release native results do not by themselves establish CI, an npm
+  publication, a tag, or a GitHub Release; those publication identities require
+  separate readback.
+
+## Deterministic checks
+
+```sh
+pnpm install
+pnpm run typecheck   # tsc --noEmit
+pnpm test            # vitest
+pnpm run lint        # oxlint
+pnpm run build       # tsdown
+pnpm pack --dry-run --json
+```
+
+## Isolated profile composition (macOS, no real ~/.dsh)
+
+```sh
+export DSH_HOME=/tmp/dsh-context-guard-smoke
+DSH=/path/to/dsh
+"$DSH" plugin --profile web add "file:/abs/path/to/dsh-context-guard"
+"$DSH" --profile web --dump-config | grep context-guard
+"$DSH" plugin --profile headless add "file:/abs/path/to/dsh-context-guard"
+"$DSH" --profile headless --dump-config | grep context-guard
+```
+
+Verified result: both profiles contain `id: context-guard, name: dsh-context-guard` in the composed tree.
+
+## Native load
+
+A real headless boot loads the plugin and advances to the model call; it stops at `MISSING_CREDENTIAL` when no provider key is configured. That is the expected boundary for a load check and is unrelated to plugin correctness.
+
+## Verified
+
+- Web UI command rendering and the `/context-guard on|off|status|diagnose` subcommands produce the expected `command/run`/`command/done` (round-5 isolated profile); `/context-guard diagnose` was re-verified in round-8.
+- A complete macOS headless task in an isolated profile created one artifact,
+  read it back as durable evidence, rejected an incomplete first binding, then
+  certified the complete requirement and acceptance set before `turn/end`.
+
+## v0.2.0 Windows acceptance status
+
+The GitHub tag `v0.2.0` resolves to release commit `c107cd8`. The GitHub
+Release is published at
+https://github.com/GreenLv/dsh-context-guard/releases/tag/v0.2.0.
+
+Windows 0.2.0 native runtime acceptance completed in the separate live DSH
+Web session. The loaded package version was `0.2.0`. The supported PowerShell
+command
+
+`Set-Content -LiteralPath 'D:\dsh-pwsh-acceptance\pwsh-acceptance-020.txt' -Value 'guard-test' -Encoding ascii -NoNewline`
+
+created the artifact successfully after the documented permission-boundary
+retry. An independent `read` returned exactly `guard-test` with no trailing
+newline. The durable evidence IDs from that session were `E0009` for the
+successful PowerShell write and `E0011` for the independent read.
+
+The session's checkpoint attempt was `incomplete`, and a follow-up session
+also rejected `E0009` and `E0011` because those IDs are not present in its
+current session projection. Context Guard currently derives evidence from the
+active DSH event log only; it has no cross-session evidence import or lookup
+contract. The runtime actions and their outputs are therefore recorded as
+completed runtime acceptance, but the v0.2.0 checkpoint remains `incomplete`
+in this later session by design. To obtain a certificate, the commands and
+checkpoint must be performed in one session. The Windows scope is limited to
+the documented PowerShell subset and does not expand to Windows Bash or
+compound PowerShell syntax.
+
+## Native platform acceptance
+
+- macOS: an isolated real-model headless task used a supported POSIX shell
+  write and an independent read, then persisted a certified checkpoint before
+  the completed turn.
+- Windows: the v0.1.1 candidate had an isolated real-model task using
+  `pwsh Set-Content -LiteralPath` and an independent read, with a certified
+  checkpoint. The v0.2.0 runtime actions are recorded in the dedicated status
+  section above, but their cross-session checkpoint repair remains incomplete.
+
+Both final-SHA runs used clean public checkouts and isolated `DSH_HOME`
+directories. They establish native behavior for the bounded v0.1 command
+subset; they do not claim support for shell or PowerShell syntax outside the
+subset documented in `COMPATIBILITY.md`.
+
+## Public-package profile readback
+
+On macOS, the published `dsh-context-guard@0.1.0` npm package was installed into a real DSH Web profile through the pinned `codex-sync` plugin reconciler. A second dry run was a strict no-op; direct package and bundle readback reported version `0.1.0`; `dsh --profile web --dump-config` included the `context-guard` bundle; and the restarted Web command directory exposed `/context-guard`, whose `status` subcommand returned a valid projection summary.
+
+This verifies public-package consumption and real-profile loading on macOS. It does not replace the isolated model-task evidence above and does not claim a second Windows run from the public npm package.
+
+## macOS v0.1.2 acceptance (2026-08-27)
+
+Verified commit: `dd402fbaa5d37dd246056d8ecd66430e5f75f412` (annotated tag `v0.1.2`, clean checkout, `main` fast-forwarded to the tag). macOS, Node v25.1.0, pnpm 11.22.0.
+
+Gate run (exit codes and summary):
+
+- `pnpm install --frozen-lockfile` → 0.
+- `pnpm test` → 0; 5 test files, 107 tests passed.
+- `pnpm run typecheck` → 0.
+- `pnpm run lint` → 0 errors / 0 warnings (23 files, 96 rules).
+- `pnpm run build` → 0; 6 files, 123.60 kB total (`dist/index.js`, `dist/domain/index.js`, `dist/domain-CJulh_RZ.js`, `dist/index.d.ts`, `dist/domain/index.d.ts`, `dist/index-CA7Z-W_A.d.ts`).
+- `pnpm run pack:check` → 0.
+
+Artifact check: `shell exited: code` is present in `dist/`. The literal string `persistent bash shell was reset` cannot appear in any build of commit dd402fb, because the implementation parameterizes the reset line as `/^The persistent (?:bash|pwsh) shell was reset;/` to cover both persistent renderers (`src/domain/evidence.ts` `PERSISTENT_RESET_LINE`). Equivalent checks pass: the regex is present in `dist/domain-CJulh_RZ.js` (line 1059), it matches the rendered Bash and pwsh prose lines (run through `RegExp.test`), and the built `dist` module replays all eight 0.1.2 cases (`[shell exited: code 1]`, `[shell killed by signal: SIGTERM]`, `[shell exited]`, timeout intro — each with and without the reset prose; plus `[shell exited: code 0]` → success and reset-prose-only → success) with the expected outcomes.
+
+Publication readback: `npm view dsh-context-guard dist-tags.latest` = `0.1.2`; registry `gitHead` = `dd402fbaa5d37dd246056d8ecd66430e5f75f412`; the official tarball `dsh-context-guard-0.1.2.tgz` unpacks to version `0.1.2` with both artifacts above, and all six `dist/` files are byte-identical (md5) to the local build — the published artifact matches the gate-run build.
+
+Installed state (macOS, real `~/.dsh`, `codex-sync` managed): pin raised `0.1.1` → `0.1.2` in `config/dsh/plugins.toml`; `--check-updates` reported the pin current; the pre-apply dry run planned exactly one UPDATE; `--apply` ran the single `dsh plugin --profile web add dsh-context-guard@0.1.2` pass; `~/.dsh/profiles/web/node_modules/dsh-context-guard/package.json` reads `0.1.2`, the installed `dist/` carries both vocabulary markers, the package stays in `dsh.profile.bundles`, and a follow-up dry run is a no-op (`No DSH plugin changes needed`). DSH was restarted (process started 23:41:05, after the 23:39:17 install) so the live instance loads 0.1.2.
+
+Smoke (in the live guarded session, 0.1.2 loaded): a clean foreground `pnpm test` in this repository completed with 5 files / 107 tests passed and produced no terminal marker; the guard-derived evidence (`E0065`, bash, repo scope) carries outcome `success`, and the checkpoint binding `{R042, [E0065]}` was accepted with no rejected bindings — the clean foreground bash result both scores `success` and certifies its matching item, confirming the 0.1.1 clean-success contract still holds under 0.1.2 (the 0.1.1 → 0.1.2 core regression point). One earlier binding was properly rejected and is recorded, not hidden: the first smoke attempt wrapped the command in `2>&1 | tail -6; echo ...`, which the guard classifies as non-deterministic with no supported operations; the binding `{R041, [E0058]}` failed the run contract, and no binding rule was changed for it. A subsequent clean run was used for the accepted binding.
+
+This section records the live-profile acceptance of v0.1.2 on macOS. It does not claim completion of the session's full 55-item contract, which was not part of this smoke; it does not re-claim any Windows result.

package/docs/PORTING_NOTES.md

@@ -0,0 +1,14 @@
+# Porting Notes
+
+The DSH implementation ports deterministic Context Guard semantics from `GreenLv/codex-context-guard` v0.8.8 while replacing the platform layer.
+
+| Area | Treatment |
+| --- | --- |
+| canonicalization, hashing, IDs | Port to TypeScript |
+| contract capture and supersession | Port as pure domain functions |
+| evidence and proof binding | Adapt to DSH durable tool-result events |
+| recovery and stop policy | Adapt to DSH agent lifecycle |
+| Codex hooks, cache manager, Python runtime | Delete from DSH runtime |
+| multimodal assets, subagent provenance, rollover | Defer beyond 0.1.0 |
+
+The DSH port derives all guard state from natively persisted DSH session events (`command/run`, `user/message`, `tool/call`, `tool/result`, `tool/code-dispatch*`) instead of the removed custom event vocabulary, wires the completion gate to Goal interception and agent scoping, and enforces fail-closed certification. Native isolated real-model acceptance has passed on macOS and Windows, and the public npm package has been loaded and exercised in a real macOS Web profile. These results cover the bounded v0.1 command subset; they do not broaden it into general shell or PowerShell analysis or claim a second Windows run from the public package.

package/docs/PRIVACY.md

@@ -0,0 +1,23 @@
+# Privacy
+
+Context Guard stores only bounded, deterministic facts. It does not persist prompt or tool-output bodies.
+
+## Stored
+
+- Normalized clause text (single-line, whitespace-collapsed) and its SHA-256.
+- Stable identifiers (R/A/P/E/C), revision, epoch, and event sequence references.
+- Tool name, call/result seq, outcome enum, capability, subject, and surface.
+- A bounded summary hash (truncated to 240 characters before hashing).
+
+## Never stored
+
+- Complete prompts, stdout, stderr, or file contents.
+- Authorization headers, URL query values, credentials, or API keys.
+- Image bytes or binary contents.
+- Authenticated session state or raw transcripts.
+
+## Failure behavior
+
+- Unknown, failed, or object-mismatched evidence cannot certify completion.
+- Without a durability checkpoint, evidence is recorded as `unknown`.
+- Corrupt or unknown Guard state refuses certification rather than guessing.

package/docs/UPSTREAM_BASE.md

@@ -0,0 +1,22 @@
+# Upstream Base
+
+This repository ports deterministic semantics from an existing Codex product; it is a new, independently owned repository with a fresh history.
+
+## Semantic baseline
+
+- Repository: `https://github.com/GreenLv/codex-context-guard`
+- Version: `v0.8.8`
+- Tag object: `827602ca96653a53c00e9fae088bb46003509dc6`
+- Peeled source commit: `e661370442183913b717ec2535609377bbb8664a`
+- License: Apache-2.0
+- Key contracts: private state schema 7, Proof protocol 1.0.0, Stop protocol 1.1.0
+
+## Reused vs replaced
+
+Reused as behavior: canonicalization, hashing, stable identity, requirement/acceptance/prohibition capture, append-only supersession, evidence outcome classification, subject/surface matching, proof and stop semantics, recovery priority, completion classification.
+
+Replaced: the Codex Hook runtime, Python subprocess, plugin cache installer, and `PLUGIN_DATA` state path. The DSH runtime is TypeScript over the Session event log; it does not use the Codex Hooks bridge.
+
+## Not copied
+
+Codex installer/manager code, Hook cache lifecycle, private runtime data, transcripts, credentials, and commit history are intentionally absent.