Add the zcode write-path guard instance with its adaptation matrix
Why: zcode lacks a rules feature (AGENTS.md is the resident layer) but supports PreToolUse hooks that can block Edit/Write before the write lands, upgrading A1/A3 from commit-time to write-time enforcement; the two block shapes (integration branch, detached submodule) mirror the real incidents. Evidence: script-level suite 8/8 (N1-N3 blocks with exit 2 and remediation hints, P1-P5 allows incl. fail-open degradation paths); config JSON valid; client-side live-fire interception marked pending-live in the matrix. Impact: .zcode/config.json enables the hook runner for this workspace; .zcode/plans/ ignored (client state); no product code change. Refs: Development-Guidelines 0.1.0-draft.8; policy/tool-adaptation-zcode.md
This commit is contained in:
@@ -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 实例矩阵证据(机制未变)
|
||||
Reference in New Issue
Block a user