dsh-completion-guard 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.5.3 - 2026-09-14
+
+### Fixed
+
+- Preparation succeeds when the host capability check has no reason code. Real tool-registry regressions cover the previously invalid nested optional field.
+- Git preparation lists the required inputs and call sequence. Missing evidence inputs identify their exact fields; producer-computed Git identities are no longer presented as missing user targets. Execution and certification checks remain unchanged.
+
+### Planned
+
+- Track answer delivery separately from execution certification. The design and remaining semantic coverage are recorded in [next-version repair notes](docs/NEXT_VERSION_REPAIR_NOTES.md); question closure is not changed by this patch.
+
 ## 0.5.2 - 2026-09-11
 
 ### Changed

package/CHANGELOG.zh-CN.md

@@ -2,6 +2,17 @@
 
 本项目的重要变化记录在这里。项目仍处于 1.0 之前；版本号跟踪插件生命周期，不代表 API 已稳定。
 
+## 0.5.3 - 2026-09-14
+
+### 修复
+
+- 宿主能力检查没有原因码时，准备工具也能正常返回。通过真实工具注册入口覆盖此前非法的嵌套可选字段。
+- Git 准备结果列出所需参数与调用顺序，取证缺参时指出具体字段；不再把生产者读取的 Git 身份列为用户缺少的目标。执行与认证校验保持原有要求。
+
+### 后续计划
+
+- 将回答交付与执行认证分开记录。设计及剩余语义覆盖见[下版修复记录](docs/NEXT_VERSION_REPAIR_NOTES.md)；本次补丁未改变问答关闭规则。
+
 ## 0.5.2 - 2026-09-11
 
 ### 变化

package/README.md

@@ -6,6 +6,9 @@ An add-on for DeepSeek Harness (DSH) that keeps a task's requirements and checks
 
 ![Task-contract clauses and bounded evidence pass through a checkpoint before a completion certificate is issued](assets/social/completion-guard-hero.png)
 
+
+Source candidate **0.5.3** fixes preparation failures and explains the Git evidence sequence. The published installation below remains 0.5.2 until the new package is verified on npm. See the [candidate changes](CHANGELOG.md) and [remaining semantic work](docs/NEXT_VERSION_REPAIR_NOTES.md).
+
 ## Quick start
 
 Install the published **0.5.2** release into the DSH Web environment:
@@ -28,7 +31,7 @@ GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-l
 dsh --profile web --dump-config | "$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config -
 ```
 
-On Windows, run the same three subcommands through `dsh-completion-guard-host-lock.cmd` in the Web settings directory's `node_modules\.bin` directory and use Windows absolute paths. The preceding 0.5.1 package passed separate macOS and Windows native acceptance on DSH `0.1.5-rc.2`; each 0.5.2 artifact keeps its own acceptance identity in the [acceptance record](docs/LOCAL_ACCEPTANCE.md). Other host versions and artifacts need their own native evidence. Repeat this check after changing DSH, Guard or the profile location; an ordinary market-only update does not require reinjection. The Guard stays unavailable if the active package set is missing, mixed, duplicated, or different from a checked setup.
+On Windows, run the same three subcommands through `dsh-completion-guard-host-lock.cmd` in the Web settings directory's `node_modules\.bin` directory and use Windows absolute paths. The published 0.5.2 package passed separate macOS and Windows native acceptance on DSH `0.1.5-rc.2`; both runs are bound to its exact bytes in the [acceptance record](docs/LOCAL_ACCEPTANCE.md). Other host versions and artifacts need their own native evidence. Repeat this check after changing DSH, Guard or the profile location; an ordinary market-only update does not require reinjection. The Guard stays unavailable if the active package set is missing, mixed, duplicated, or different from a checked setup.
 
 Restart DSH Web, open a session, and enable the Guard:
 

package/README.zh-CN.md

@@ -6,6 +6,9 @@
 
 ![任务合同条款与有界证据通过 checkpoint 匹配后签发完成证书](assets/social/completion-guard-hero.png)
 
+
+源码候选 **0.5.3** 修复准备工具报错，并补充 Git 取证顺序。下方公开安装版本暂为 0.5.2，待新包在 npm 发布并回读后更新。详见[候选变更](CHANGELOG.zh-CN.md)与[后续语义工作](docs/NEXT_VERSION_REPAIR_NOTES.md)。
+
 ## 快速开始
 
 将已发布的 **0.5.2** 安装到 DSH 的 Web 运行环境：
@@ -28,7 +31,7 @@ GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-l
 dsh --profile web --dump-config | "$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config -
 ```
 
-Windows 请通过 Web 配置目录下的 `node_modules\.bin\dsh-completion-guard-host-lock.cmd` 运行相同的三个子命令，并使用 Windows 绝对路径。前一版 0.5.1 包已在 DSH `0.1.5-rc.2` 上分别通过 macOS 和 Windows 原生验收；0.5.2 的每个制品身份由[验收记录](docs/LOCAL_ACCEPTANCE.md)单独绑定。其他宿主版本和制品仍需各自的原生证据。DSH、Guard 或 profile 路径变化后需要重新检查；仅 market 普通升级不需要重新注入。如果当前包集合缺失、混装、重复或不属于已检查环境，Guard 会保持不可用。
+Windows 请通过 Web 配置目录下的 `node_modules\.bin\dsh-completion-guard-host-lock.cmd` 运行相同的三个子命令，并使用 Windows 绝对路径。已发布的 0.5.2 包在 DSH `0.1.5-rc.2` 上分别通过 macOS 和 Windows 原生验收；两次运行均在[验收记录](docs/LOCAL_ACCEPTANCE.md)中绑定同一份精确制品。其他宿主版本和制品仍需各自的原生证据。DSH、Guard 或 profile 路径变化后需要重新检查；仅 market 普通升级不需要重新注入。如果当前包集合缺失、混装、重复或不属于已检查环境，Guard 会保持不可用。
 
 然后重启 DSH Web，打开会话并启用 Guard：
 

package/dist/index.js

@@ -848,6 +848,35 @@ function createBoundaryTool(getProjection, prepare, onRejected) {
 	});
 }
 
+//#endregion
+//#region src/tools/git-preparation.ts
+/** Input recipes are guidance only; live resolution remains authoritative. */
+function gitPreparation(action) {
+	if (![
+		"commit",
+		"push",
+		"fetch",
+		"pull"
+	].includes(action)) return void 0;
+	return {
+		selector_fields: action === "commit" ? ["repository", "branch"] : [
+			"repository",
+			"remote",
+			"refspec"
+		],
+		command_manifest_fields: ["planned_tool", "planned_arguments"],
+		planned_tools: ["bash", "pwsh"],
+		planned_argument_fields: ["command", "workdir"],
+		steps: [
+			"Before execution: context_guard_evidence with evidence_role=resolution, selector and command_manifest. Keep the successful tool call ID and target_digest.",
+			"Execute once with context_guard_action, semantic_action, resolution_call_id, target_digest, contract_item_id and contract_item_revision.",
+			"Collect effect and state separately with context_guard_evidence, using the same resolution_call_id and the successful action call ID as effect_call_id.",
+			"Checkpoint the matching resolution/effect/state evidence IDs. Call IDs identify tool events; evidence IDs identify checkpoint facts.",
+			"If the action already ran without resolution, report the historical evidence gap and read back state. Do not repeat a mutation to create missing prestate evidence."
+		]
+	};
+}
+
 //#endregion
 //#region src/tools/prepare.ts
 /**
@@ -920,7 +949,8 @@ function createPrepareTool(options) {
 				"effect (the exact planned change)",
 				"state (independent post-state readback)"
 			] : ["state (matching durable evidence for the requested verification)"];
-			const missingTargetFields = manifestEntry?.stateful && plannedAction ? manifestEntry.resolvedTargetKeys.filter((key) => !(item.requestedTarget?.[key] !== void 0 || args.requested_target?.[key] !== void 0)) : [];
+			const recipe = plannedAction ? gitPreparation(plannedAction) : void 0;
+			const missingTargetFields = manifestEntry?.stateful && plannedAction ? (recipe?.selector_fields ?? manifestEntry.resolvedTargetKeys).filter((key) => !(item.requestedTarget?.[key] !== void 0 || args.requested_target?.[key] !== void 0)) : [];
 			const capability = plannedAction && options.hostCapability ? options.hostCapability(plannedAction) : void 0;
 			const commandShape = options.commandTemplate && plannedAction ? options.commandTemplate(plannedAction) : void 0;
 			return {
@@ -937,8 +967,9 @@ function createPrepareTool(options) {
 				missing_target_fields: missingTargetFields,
 				...capability ? { host_capability: {
 					status: capability.status,
-					reason_code: capability.reasonCode
+					...capability.reasonCode !== void 0 ? { reason_code: capability.reasonCode } : {}
 				} } : {},
+				...recipe ? { evidence_input_contract: recipe } : {},
 				note: "Preparation performs no action. A default or guessed target is not user authority; explicit root instruction is required for missing target fields."
 			};
 		}
@@ -1037,12 +1068,14 @@ function adapterId(action) {
 	if (action === "publish") return "context-guard.registry.v1";
 	return "context-guard.git.v1";
 }
-function unavailable(action, role, reason) {
+function unavailable(action, role, reason, missingFields, nextStep) {
 	return {
 		status: "unavailable",
 		reason_code: reason,
 		semantic_action: action,
 		evidence_role: role,
+		...missingFields?.length ? { missing_fields: missingFields } : {},
+		...nextStep ? { next_step: nextStep } : {},
 		resolved_target: {},
 		observed_state: {},
 		adapter_id: adapterId(action),
@@ -2292,6 +2325,11 @@ function createEvidenceTool(options = {}) {
 						type: "string",
 						required: true
 					},
+					missing_fields: {
+						type: "array",
+						items: { type: "string" }
+					},
+					next_step: { type: "string" },
 					evidence_role: {
 						type: "string",
 						required: true,
@@ -2414,6 +2452,18 @@ function createEvidenceTool(options = {}) {
 			if (!agent) return unavailable(action, role, "producer_agent_unavailable");
 			try {
 				if (role === "resolution") {
+					const recipe = gitPreparation(action);
+					if (recipe) {
+						const manifest = record(args.command_manifest);
+						const plannedArgs = record(manifest?.planned_arguments);
+						const selector = record(args.selector);
+						const missing = [
+							...recipe.selector_fields.filter((key) => !requireString(selector ?? {}, key)).map((key) => `selector.${key}`),
+							...!requireString(manifest ?? {}, "planned_tool") ? ["command_manifest.planned_tool"] : [],
+							...recipe.planned_argument_fields.filter((key) => !requireString(plannedArgs ?? {}, key)).map((key) => `command_manifest.planned_arguments.${key}`)
+						];
+						if (missing.length) return unavailable(action, role, "resolution_input_missing", missing, "Supply the listed resolution inputs before execution. Use context_guard_prepare for the exact Git input contract. A manifest_id alone does not describe a planned tool call.");
+					}
 					const executable$1 = executableFor(action);
 					const executableBinding = executable$1 ? await (roots.readExecutableIdentity ?? executableIdentity)(executable$1, exec.signal) : void 0;
 					if (executable$1 && !executableBinding) return unavailable(action, role, "executable_identity_unavailable");
@@ -2425,7 +2475,7 @@ function createEvidenceTool(options = {}) {
 					if (!expectedTransition) return unavailable(action, role, "expected_transition_unavailable");
 					return supported(action, role, resolved.target, {}, commandManifest, gitBinding, executableBinding, expectedTransition);
 				}
-				if (!args.resolution_call_id) return unavailable(action, role, "producer_reference_missing");
+				if (!args.resolution_call_id) return unavailable(action, role, "producer_reference_missing", ["resolution_call_id", ...!args.effect_call_id ? ["effect_call_id"] : []], "Use the successful pre-action resolution call ID and matching action call ID. Selectors and evidence IDs cannot replace call IDs. If execution already happened without resolution, report the historical gap; do not repeat the mutation.");
 				const resolution = findResolution(snapshotSessionEvents(agent.session), args.resolution_call_id, action);
 				if (!resolution) return unavailable(action, role, "persisted_effect_mismatch");
 				const executable = executableFor(action);
@@ -2444,7 +2494,7 @@ function createEvidenceTool(options = {}) {
 					"pull",
 					"fetch"
 				].includes(action);
-				if (!args.effect_call_id) return unavailable(action, role, "producer_reference_missing");
+				if (!args.effect_call_id) return unavailable(action, role, "producer_reference_missing", ["effect_call_id"], "Supply the successful matching effect call ID. Git/package/service effects must come from context_guard_action; do not repeat an already completed mutation to manufacture missing evidence.");
 				if (ownedEffect) {
 					const events = snapshotSessionEvents(agent.session);
 					const actionCall = actionCallMatches(events, args.effect_call_id, action, args.resolution_call_id, resolution.target);

package/docs/LOCAL_ACCEPTANCE.md

@@ -2,6 +2,16 @@
 
 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.
 
+## 0.5.2 published release (2026-09-11)
+
+[Version 0.5.2](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.2) is published on GitHub and [npm](https://www.npmjs.com/package/dsh-completion-guard/v/0.5.2). The annotated tag and npm `gitHead` identify commit `e8b21b3d0bb5b3864c856cc9ea6bd19d5ab066ef`. The frozen 303412-byte, 27-file tgz has SHA-256 `d975f17dc3bfed999cbe6c0e638b226c3dcf8651f288ea7ab83faa5ba7903d31`.
+
+The local deterministic matrix and [exact-candidate portability CI](https://github.com/GreenLv/dsh-completion-guard/actions/runs/34577054241) passed. Separate macOS and Windows runs on DSH `0.1.5-rc.2` each passed all 28 required host-bound gates for these same bytes, with cleanup passed. Both annexes retain the `real_model_request` skip; no real-model task, daily-profile adoption, or rc.1 native run is claimed for this artifact.
+
+Anonymous public readback verified the annotated tag target, npm version and `latest` tag, embedded `gitHead`, registry integrity, and downloaded tgz bytes. The GitHub Release title is `DSH Completion Guard 0.5.2`. All seven attachments matched the accepted files: the tgz, checksum, artifact manifest, and separate native annexes and transfer receipts for macOS and Windows. The public package publishes `0.1.5-rc.2 || 0.1.5-rc.1` consistently in the top-level DSH engine field, nested plugin engine field, and all seven DSH peer dependencies.
+
+This section and the updated main-branch installation guidance are post-release documentation. The published tag and npm package retain their original bytes.
+
 ## 0.5.1 published release (2026-09-11)
 
 [Version 0.5.1](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.1) is published on GitHub and [npm](https://www.npmjs.com/package/dsh-completion-guard/v/0.5.1). The annotated tag and npm `gitHead` identify commit `aefdeaf2737ef1c99f1170085140c93a515e1125`. The frozen 303460-byte, 27-file tgz has SHA-256 `5e00ddf2f9772b1ae2ca3665d7c4ce858b814dc26a4116388082db2d625da28d`.

package/docs/NEXT_VERSION_REPAIR_NOTES.md

@@ -0,0 +1,54 @@
+# 下个版本：准备工具、Git 取证与问答残留
+
+状态：未发布的增量修复与后续设计记录，2026-09-14。修复基线为 DSH Completion Guard 0.5.2。本页持续补充，不是发布或原生验收记录；下一候选版本为 0.5.3；正式发布身份以独立制品和发布回读为准。
+
+## 已实施的局部修复
+
+### 准备工具返回合法 JSON
+
+宿主能力检查成功时可以不携带 reasonCode，但 prepare 将其写成 host_capability.reason_code: undefined。DSH 在渲染前检查返回值是否为无损 JSON，因此拒绝整个调用。不存在的条目和错误 revision 提前返回，不经过此字段。
+
+现在只有定义了 reasonCode 才输出 reason_code。注册期回归使用真实成功结果的形状，不再人为补一个成功原因来掩盖问题；覆盖 generic_run、commit、install、verify、push 和错误分支。该缺陷属于插件输出契约，跨操作系统，不应归因于 Windows 宿主拒绝合法数据。
+
+### Git 取证给出可执行的准备信息
+
+prepare 新增 evidence_input_contract：列出 selector、command_manifest、planned_arguments 的字段和完整调用顺序。Git 的 missing_target_fields 只列调用方需要提供的 selector 字段；前置 HEAD、暂存区摘要和源提交等由生产者读取，不要求用户伪造。
+
+resolution 缺少输入时，evidence 在探测可执行程序前返回 resolution_input_missing、missing_fields 和 next_step。effect/state 缺少前置调用引用时保留 producer_reference_missing，并明确缺少 resolution_call_id 或 effect_call_id。这些新增字段只解释失败，不改变证据事实、摘要或认证权限。
+
+正确顺序：
+
+1. 暂存需要提交的改动后，先请求 resolution。commit 的 selector 是 repository、branch；push/fetch/pull 是 repository、remote、refspec。
+2. Git command_manifest 只包含 planned_tool 和 planned_arguments；planned_tool 为 bash 或 pwsh，planned_arguments 只包含 command 和 workdir。命令必须匹配 prepare 给出的受支持形态；workdir 与 repository 一致。manifest_id 不是该输入的替代品。
+3. 用成功 resolution 的调用 ID、target_digest 和当前条目 ID/revision 调用 context_guard_action 执行一次。
+4. 分别请求 effect 和 state，均引用同一 resolution_call_id 和成功 action 的 effect_call_id。
+5. checkpoint 引用三种角色对应的 evidence ID。工具 call ID 与证据 evidence ID 不可混用。
+
+已有动作如果绕过这条链执行，普通回读仍能报告实际结果，但无法补造执行前证据。不要重复提交或推送来填补历史证据缺口。
+
+## 事故结论的修正
+
+两次 Windows 对话确实观察到 prepare 输出错误和 Git 取证失败。独立核对后，不能把缺参调用的失败推广为“Git 适配器完全不可达”：resolution 调用未提供计划工具清单，effect/state 调用未提供前置调用引用。adapter_id 标识尝试的适配路径，不代表本次产生了可用事实；selector 不接受 commit 字段也不表示缺少提交支持。
+
+现有真实临时仓库测试覆盖 commit/push/fetch/pull 的受控执行和独立回读。它们不能替代 Windows 日常宿主验收。Windows 中 Git 子进程创建 signal pipe 失败另属执行环境问题，不能由本次输出契约修复宣称解决。没有真实等待或延后资格时，boundary 拒绝仍是正常保护，不应为结束一次对话伪造资格。
+
+## 待设计：问答交付与执行认证分离
+
+本轮没有改变需求捕获、pending 状态、证书或恢复关闭规则。当前调查/问答可能已交付给用户，却仍以未认证条目保留；复杂表达又可能被识别为 generic_run。不能将这个已知缺口写成已修复。
+
+后续设计沿用上游 [Semantic Compatibility](https://github.com/GreenLv/codex-context-guard/blob/main/docs/SEMANTIC_COMPATIBILITY.md) 的边界：共享语义由上游拥有，DSH 保留独立宿主、持久化和运行时。当前镜像不意味着自动采用 Codex 0.13.x 的全部行为。既有分析还包括 effectiveness 仓库的 docs/SEMANTIC_BOUNDARIES.md，指出有限句型只能保证已覆盖语法，不能证明一般语义完备。
+
+下一批工作须定义：
+
+- 原文跨度对应信息交付、执行、约束和未知部分；未覆盖跨度保持可见，不由模型摘要替代原文。
+- 回答交付记录绑定当前根用户输入、宿主 turn 和最终回答；交付不等于内容正确或执行认证。
+- 混合请求的回答部分可以记录交付，修改、测试、发布等仍需独立证据；子项交付不能关闭父项全部工作。
+- 未知表达保持可解释的未决状态，禁止靠增加关键词或删除 pending 条目掩盖问题。观察模式先评估误关闭与误保留，再决定版本化切换。
+- 延迟回复、子代理回复、压缩摘要、引用历史和中止 turn 不能误绑定为当前回答；恢复保持已验证的交付与未完成执行。
+- 旧证书、旧投影和升级边界必须明确；新增共享行为先在上游形成中立合成用例，再按精确 pin 适配，不能静默改写冻结镜像。
+
+验收需分别覆盖纯问答、附流程图说明、长复合提问、解释后执行、未知尾句、条件/否定、双语、跨 turn、compact/resume 和旧状态。记录误保留、误关闭及额外轮次，不能仅用总测试通过率评价语义覆盖。
+
+## 验证边界
+
+本轮局部修复使用宿主注册、诊断和取证测试，以及仓库映射所要求的本地检查。更新 dist 只代表生成源码产物；旧 0.5.2 制品和已加载插件不变。新候选的 CI、Windows/macOS 原生验收、冻结制品、安装和发布均需后续独立完成。Codex 本轮仅新增问题与设计文档，不修改其运行时。

package/docs/distribution.md

@@ -25,12 +25,14 @@ version and annotated tag are retained for audit history; the npm version is
 deprecated with `Release metadata incomplete; use dsh-completion-guard@0.3.1.`
 Version 0.3.1 repairs the provenance-bearing frozen-package workflow.
 
-## Published v0.5.1 destinations (2026-09-11)
+## Published v0.5.2 destinations (2026-09-11)
 
-1. [GitHub Release `v0.5.1`](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.1) is a non-draft, non-prerelease release. Its annotated tag identifies commit `aefdeaf2737ef1c99f1170085140c93a515e1125`.
-2. [`dsh-completion-guard@0.5.1` on npm](https://www.npmjs.com/package/dsh-completion-guard/v/0.5.1) is published and `latest` resolves to `0.5.1`. Its `gitHead` equals that release commit. The registry download and Release tgz match SHA-256 `5e00ddf2f9772b1ae2ca3665d7c4ce858b814dc26a4116388082db2d625da28d`.
+1. [GitHub Release `v0.5.2`](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.2) is a non-draft, non-prerelease release named `DSH Completion Guard 0.5.2`. Its annotated tag identifies commit `e8b21b3d0bb5b3864c856cc9ea6bd19d5ab066ef`.
+2. [`dsh-completion-guard@0.5.2` on npm](https://www.npmjs.com/package/dsh-completion-guard/v/0.5.2) is published and `latest` resolves to `0.5.2`. Its `gitHead` equals that release commit. The registry download and Release tgz match SHA-256 `d975f17dc3bfed999cbe6c0e638b226c3dcf8651f288ea7ab83faa5ba7903d31`. The public package exposes `0.1.5-rc.2 || 0.1.5-rc.1` in both DSH engine fields and all seven DSH peer dependencies.
 3. All seven Release attachments were downloaded and matched the accepted files. The separate macOS and Windows annexes each record 28 required gates passed on DSH `0.1.5-rc.2`, with real-model requests skipped. See [acceptance details](LOCAL_ACCEPTANCE.md).
 
+Version 0.5.1 remains available as an immutable historical release.
+
 ## Historical v0.4.0 destinations
 
 1. [GitHub Release `v0.4.0`](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.4.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-completion-guard",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "A task-contract and completion-certification layer for DeepSeek Harness.",
   "repository": {
     "type": "git",
@@ -113,5 +113,5 @@
     "hooks",
     "typescript"
   ],
-  "gitHead": "e8b21b3d0bb5b3864c856cc9ea6bd19d5ab066ef"
+  "gitHead": "a7baccdfbc538aa071941ebb36aa41fa9bf6e709"
 }