Merge pull request 'Add the zcode write-path guard instance with its adaptation matrix' (#7) from feature/zcode-hooks into main

2026-09-30 03:43:38 +00:00
parent 1e08eb6ba2 ffa8dd63c2
commit 20727a8fd3
7 changed files with 119 additions and 0 deletions
@@ -1,3 +1,4 @@
 /bin/
 node_modules/
 /data/
+.zcode/plans/
@@ -25,3 +25,4 @@
 | 同步前验收 | 3092715bf68bc4cefb6515c157cd90cf9b5cba2e | f31fd5f62d3dd09780689e53f16c7da94215cbd1 | 2026-09-30T03:12:18Z |
 | 同步前验收 | 923591feda367bc8ceaf809ed7c294e5245a3a3a | 3366148dcf660148c58dff8ec56e02d80604c7a0 | 2026-09-30T03:23:31Z |
 | 同步前验收 | 428628ffe2a1b73a86299716853f52abdbd16291 | 6fa07f3d15ad4a59f11a53cabc39c5edf3bba2bf | 2026-09-30T03:35:08Z |
+| 同步前验收 | 1e08eb6ba22c82a1e87afbabe9a15f3e0a46a671 | ccddcc2b2b245745a38381cf50cdea3f39b45e5b | 2026-09-30T03:43:26Z |
@@ -0,0 +1,25 @@
+# feature/zcode-hooks 任务卡
+
+任务主记录：<PR 链接，task-finish 时填写>；状态：进行中；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 1e08eb6ba22c82a1e87afbabe9a15f3e0a46a671
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-zcode-hooks（worktree）；分支：feature/zcode-hooks
+- 授权与交付终点：<本次允许的动作与终点；未授权事项写明>
+
+## 目标与非目标
+
+<预期结果、受影响入口/模块/契约；明确不做什么。>
+
+## 同步记录
+
+| 节点 | sync_base_sha | tested_head_sha | checked_at |
+|---|---|---|---|
+| 启动 | 1e08eb6ba22c82a1e87afbabe9a15f3e0a46a671 | 1e08eb6ba22c82a1e87afbabe9a15f3e0a46a671 | 2026-09-30T03:41:53Z |
+
+## 结果与验证（完成后填写）
+
+- 结果：
+- 验证：
+- 影响与剩余项：
@@ -0,0 +1,20 @@
+{
+  "hooks": {
+    "enabled": true,
+    "events": {
+      "PreToolUse": [
+        {
+          "matcher": "Edit|Write|ApplyPatch",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "bash \"${ZCODE_PROJECT_DIR}/scripts/zcode/write-guard.sh\"",
+              "timeout": 15,
+              "statusMessage": "检查写入目标的工作区状态（门禁 A1/A3）"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
@@ -17,6 +17,7 @@
 | standards/multi-repo.md | 跨仓/gitlink | manual；受控历史迁移通道已于 2026-09-30 行使一次（documents/records/2026-09-30-history-migration.md） |
 | 工作区回收 | 交付终点 | advisory（task-finish）；负例：合入前 finish 拒绝输出 |
 | standards/tool-adaptation.md（draft.8） | 为工具创建规则/钩子实例 | 本组合 CLI/git 级实例已登记：policy/tool-adaptation-matrix.md（A1–A7 逐行定级+正负例证据） |
+| 同上（zcode 实例） | zcode 客户端写路径 | policy/tool-adaptation-zcode.md：PreToolUse 写守卫（.zcode/config.json + scripts/zcode/write-guard.sh），A1/A3 落笔前 enforced |

 ## 项目差异

@@ -0,0 +1,33 @@
+# zcode 客户端机制实例——能力矩阵
+
+- 适配对象：zcode CLI（工作区级配置）
+- 依据：Development-Guidelines 0.1.0-draft.8（c9ab623）standards/tool-adaptation.md + policy/adoption.md
+- 状态：verified（脚本级正负例 8/8；客户端实弹拦截待下个会话日志确认，见备注）
+- 实例位置：.zcode/config.json（PreToolUse 钩子）、scripts/zcode/write-guard.sh、AGENTS.md（常驻条文 = zcode 的 rules 层）
+- 单一权威声明：本实例是上述规范的机制实现，语义以库与项目入口为准
+
+## 能力矩阵
+
+| 要求 | 等级 | 机制（执行时机） | 正例证据 | 负例证据 | 备注 |
+|---|---|---|---|---|---|
+| A1 启动门禁 | enforced（写路径）+ advisory（检测纪律） | PreToolUse 拦 Edit/Write/ApplyPatch：目标仓在集成分支、detached HEAD、坏分支名时 exit 2 阻断（落笔前，git 钩子只拦提交时） | 脚本套件 P1–P4 放行 | N1 main 拦截、N2 detached 子仓拦截、N3 坏分支名拦截（均 exit 2 带指引） | detached 拦截正是多租户事故形态；检测/verdict 仍靠 precheck 纪律 |
+| A2 节点同步 | advisory | 无对应 zcode 事件；走 task-sync 纪律 | Dev PR#1–6 均经 sync | 实战脏树拒绝 | 不虚报 |
+| A3 集成分支保护 | enforced(local) 双层 | zcode 写路径（落笔前）+ git pre-commit（提交时）；平台分支保护未配置 | 12+ PR 全走平台 | N1 + 套件 hook-main-refused | 平台层配置后升级 |
+| A4 提交与任务记录格式 | enforced(local) 主题行 + manual body | git commit-msg 钩子（对 zcode 的 Bash git commit 同样生效） | 本批提交 | 套件 hook-longsubject-refused | body 四段无机器校验 |
+| A5 工作区回收 | advisory | task-finish（rm+prune 兜底） | PR#5/#6 后实战回收 | finish-before-merge 拒绝 | |
+| A6 秘密边界 | manual | token 自 ~/.secrets/gitea；守卫与配置无凭证 | 全程无明文泄漏 | 无构造负例 | 纪律项 |
+| A7 证据落盘 | manual | 完成声明附三段输出 | 各 PR body | 无构造负例 | |
+
+## 降级与失败行为
+
+| 机制 | 依赖缺失时行为 | 对应等级调整 | 解锁路径 |
+|---|---|---|---|
+| write-guard 输入解析（python3） | 缺 python3 或 stdin 无路径/垃圾 → 放行（fail-open） | A1 写路径降级 manual | 装 python3；提交时仍有 git 钩子兜底，构成第二道 |
+| write-guard（bash/git） | 脚本报错非 0/2 → 客户端记为错误事件 | 同上 | 修复后重跑套件 |
+| zcode 钩子运行器 | 配置文件钩子须 hooks.enabled=true（已设） | A1 写路径整体失效 | 客户端设置确认运行器激活 |
+
+## 验证记录
+
+- 2026-09-30 脚本级套件 8/8 PASS（N1–N3 拦截、P1–P5 放行与配置合法），执行者 weichen，输出留存任务卡
+- 客户端内实弹拦截：pending-live——下次会话对本仓做一次 main 分支写入试探，从 ZCode 日志（hook 执行记录）确认后去除本标注
+- 证据复用：A2–A7 行沿用 CLI/git 实例矩阵证据（机制未变）
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# zcode PreToolUse 写路径守卫（Edit/Write/ApplyPatch）。
+# 单一权威声明：本脚本是 Development-Guidelines standards/tool-adaptation.md
+# 要求 A1/A3 在 zcode 客户端的机制实例；语义以库与项目入口为准，本文件不复制规则正文。
+# 退出码：0 放行；2 阻断（PreToolUse 的 deny）；其余非零为错误。
+set -uo pipefail
+
+input=$(cat)
+file=$(printf '%s' "$input" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+ti = d.get("tool_input") if isinstance(d.get("tool_input"), dict) else {}
+for src in (ti, d):
+    for k in ("file_path", "path", "filename"):
+        v = src.get(k)
+        if isinstance(v, str) and v:
+            print(v)
+            sys.exit(0)
+' 2>/dev/null)
+[ -n "$file" ] || exit 0
+
+repo=$(git -C "$(dirname "$file")" rev-parse --show-toplevel 2>/dev/null) || exit 0
+branch=$(git -C "$repo" rev-parse --abbrev-ref HEAD 2>/dev/null) || exit 0
+
+deny() { echo "write-guard: 拒绝——${1}（目标 ${file}，仓库 ${repo}）" >&2; exit 2; }
+
+case "$branch" in
+  main|master)
+    deny "集成分支 ${branch} 不得直接写入；先 make task-start NAME=feature|fix/<slug>（A1/A3）" ;;
+  HEAD)
+    deny "仓库处于 detached HEAD（常为他人现场或未建分支的子仓）；先显式建任务分支（A1）" ;;
+esac
+echo "$branch" | grep -qE '^(feature|fix|hotfix|release)/[A-Za-z0-9._-]+$' \
+  || deny "分支名 ${branch} 不符 feature|fix|hotfix|release/<slug>（A3）"
+exit 0