@brightliu/ai-control 2.1.0 → 2.2.0

package/README.md

@@ -33,7 +33,8 @@ AI：（实现 → 跑测试）测试报告 4 条全绿，ai ship 发布检查
 
 ```bash
 # 1. 装工具（一次性）
-npm install -g github:BrightLiu4917/ai-control
+npm install -g @brightliu/ai-control
+# 网络装不了 npm 官方源时的备选：npm install -g github:BrightLiu4917/ai-control
 
 # 2. 装进你的项目
 cd 你的项目
@@ -55,6 +56,60 @@ ai sync                  # 只有用 Claude Code / WorkBuddy 才需要：为它
 | `ai test 名字` | 跑你项目自己的测试，报告自动按变更隔离存放 | "跑测试" |
 | `ai ship 名字` | 核对测试报告：确认过没有、报告新不新、全绿没有 | "能交付了吗"（秒级出结果） |
 
+## 完整流程（一张图看懂）
+
+```text
+                                你对 AI 说需求
+                                       │
+                        AI 先看代码，判断这事有多大
+                                       │
+      ┌──────────────────┬────────────┴───────────┬──────────────────────┐
+      ▼                  ▼                        ▼                      ▼
+【改错别字级】      【小需求 lite】            【正常需求】           【要动数据库】
+ 改注释/文档/typo   改文案、调样式             新功能、改接口          加字段、建表、迁移
+      │                  │                        │                      │
+   直接改完          AI 建变更单                AI 建变更单            完整流程再多一步：
+   不走流程          （2 个文件）              （3 个文件）           AI 先给表结构设计
+      │                  │                        │                   → 你点头 → 再给
+      │                  └──────────┬─────────────┘                   变更包（SQL+回滚）
+      │                             ▼                                 → 你再点头才许执行
+      │              ①【确认点】看变更单：改什么、                              │
+      │                动哪些文件、验收标准是哪几条用例                          │
+      │                             │                                        │
+      │              你说"确认"，然后【你本人】跑：                             │
+      │                    ai confirm 变更名        ◄─────────────────────────┘
+      │              （留痕：谁、几点、哪个版本确认的；Claude Code 下 AI 代跑会被钩子拦）
+      │                             │
+      │                      AI 开始写代码
+      │            （确认之前它想写一行业务代码都会被钩子拦住）
+      │                             │
+      │                      ai test 变更名
+      │            （跑你项目的测试，报告自动按变更隔离存放）
+      │                             │
+      │                      ai ship 变更名
+      │       ┌─────────── 秒级自动核对 4 件事 ────────────┐
+      │       │ ① 确认过没有？确认后变更单被偷改过没有？      │
+      │       │ ② 测试报告在不在？是不是本次新跑出来的？      │
+      │       │ ③ 有没有挂掉的测试？                        │
+      │       │ ④ 每条用例在报告里有没有通过记录？           │
+      │       └────────┬──────────────────┬───────────────┘
+      │            全过 ✅             有一条不过 ❌
+      ▼                │                  │
+    完事               ▼                  ▼
+              交付（动过库的附回滚 SQL）   AI 回去补，修好重新 ship
+```
+
+你全程只干三件事：**提需求 → 看变更单点头（自己敲 ai confirm）→ 等结果**。按事情大小分流：
+
+| 事情多大 | 例子 | 流程 | 你花几分钟 |
+|---|---|---|---|
+| 芝麻 | 错别字、注释 | 没有流程，直接改 | 0 |
+| 小 | 改文案、调样式 | lite：2 个文件，看一眼确认 | ~30 秒 |
+| 中 | 新功能、改接口 | 完整：3 个文件 + 自动化测试 | 2~5 分钟 |
+| 大 | 动数据库 | 完整 + 数据库两次点头 + 建议独立审查 | 5~10 分钟 |
+
+AI 以"小需求"开工、中途发现要动表或接口？门禁直接拦下、强制升级完整流程——**快速通道不是逃生通道**。
+
 ## 它靠什么管住 AI（三层，由软到硬）
 
 1. **规矩**（`AGENTS.md` + `.ai/rules/`）：63 行契约每次对话自动生效 + 20 份中文工程规则按需加载——禁止编造字段、SQL 必须带 WHERE、枚举必须 code+desc 禁止魔法值、JOIN 不许先连后分页……**这些是踩过生产事故总结的具体规则，不是"请写好代码"式的空话**。
@@ -91,7 +146,7 @@ ai sync                  # 只有用 Claude Code / WorkBuddy 才需要：为它
 不用。纯文档/注释/typo 直接改；小功能走 `--lite`（两个文件、30 秒确认）；只有动数据库、接口、权限才走完整流程。管控力度和风险成正比。
 
 **Q：AI 不守规矩怎么办？**
-说一句"按控制系统流程来"即可拽回；关键环节（越级偷渡、报告缺失或有失败）有自动检查兜底。诚实说明边界：AI 理论上可以伪造报告文件绕过检查，门禁的作用是把"张嘴谎报"变成"必须留下可查的假证据"——成本和暴露风险完全不是一个量级。
+说一句"按控制系统流程来"即可拽回；关键环节（越级偷渡、报告缺失或有失败、diff 含密钥）有自动检查兜底。诚实说明三条边界：① AI 理论上可伪造报告文件——门禁把"张嘴谎报"变成"必须留下可查的假证据"，成本和暴露风险不是一个量级；② 门禁验证"有叫这个名的通过测试"，验证不了测试写得好不好（空壳测试查不出来）——高风险变更的独立审查就是为这个准备的；③ 整套流程的启动键在 AI 手里，它压根不进流程时只有契约文字在管——所以契约做成每次对话自动加载，你发现不对说一句就能拽回。
 
 **Q：测试报告是什么格式？**
 JUnit XML——`ai test` 会按栈自动搞定：Maven 自带；Go 的输出自动转成报告（零配置，无需 gotestsum）；Vitest 自动注入内置 junit reporter；PHPUnit 自动加 `--log-junit`；仅 Jest 需要 `npm i -D jest-junit`（会提示）。测试方法名里带上用例编号（如 `test_TC01_xxx`）即可被核对。多变更并行时把报告输出到 `test-results/<变更名>/` 可互相隔离；报告必须比确认时间新——旧报告顶包会被拦下。
@@ -121,6 +176,6 @@ jobs:
 
 ## 工程质量
 
-零运行时依赖（只需 Node ≥18.17 + git）；22 个端到端验收测试 + 8 个单元测试 + 规则库引用自检（防悬空引用）；代码量硬预算写进 CI（内核 ≤1500 行、契约 ≤100 行、文档 1 份），超支即红——防止工具本身变臃肿。
+零运行时依赖（只需 Node ≥18.17 + git）；26 个端到端验收测试 + 8 个单元测试 + 规则库引用自检（防悬空引用）；代码量硬预算写进 CI（内核 ≤1500 行、契约 ≤100 行、文档 1 份），超支即红——防止工具本身变臃肿。
 
 前身 [ai-coding-fun](https://github.com/BrightLiu4917/ai-coding-fun)（v1）经 15 批真实项目迭代后彻底重构：5000 行 bash → 600 行 JS，五份文档的流程 → 两份，学习成本压缩到本 README 一页。

package/addons/export-adapters.js

@@ -13,6 +13,12 @@ function sync(root, args) {
 
   function write(p, content) {
     if (fs.existsSync(p) && !force) { skipped.push(path.relative(root, p)); return; }
+    if (fs.existsSync(p) && force && fs.readFileSync(p, "utf8") !== content) {
+      // 覆盖前备份：用户手改过的生成物不许静默丢失
+      const bak = `${p}.bak-${new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14)}`;
+      fs.copyFileSync(p, bak);
+      written.push(path.relative(root, bak) + "（原文件备份）");
+    }
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, content);
     written.push(path.relative(root, p));
@@ -97,9 +103,9 @@ function mergeClaudeSettings(root, written, skipped) {
   const p = path.join(root, ".claude", "settings.json");
   const OURS = [
     { matcher: "Write|Edit|MultiEdit|NotebookEdit",
-      hooks: [{ type: "command", command: "node .ai/hooks/guard-write.js" }] },
+      hooks: [{ type: "command", command: "node \"${CLAUDE_PROJECT_DIR:-.}/.ai/hooks/guard-write.js\"" }] },
     { matcher: "Bash",
-      hooks: [{ type: "command", command: "node .ai/hooks/guard-bash.js" }] },
+      hooks: [{ type: "command", command: "node \"${CLAUDE_PROJECT_DIR:-.}/.ai/hooks/guard-bash.js\"" }] },
   ];
   let obj = {};
   if (fs.existsSync(p)) {
@@ -111,10 +117,15 @@ function mergeClaudeSettings(root, written, skipped) {
   }
   obj.hooks = obj.hooks || {};
   obj.hooks.PreToolUse = obj.hooks.PreToolUse || [];
-  const have = JSON.stringify(obj.hooks.PreToolUse);
   let added = 0;
   for (const entry of OURS) {
-    if (!have.includes(entry.hooks[0].command)) { obj.hooks.PreToolUse.push(entry); added++; }
+    const fname = entry.hooks[0].command.match(/guard-\w+\.js/)[0];
+    const cur = obj.hooks.PreToolUse.filter((e) => JSON.stringify(e).includes(fname));
+    if (cur.length === 1 && JSON.stringify(cur[0]) === JSON.stringify(entry)) continue; // 已是最新
+    // 去掉旧版条目（如相对路径写法）再放入最新——按文件名去重，其余用户条目不动
+    obj.hooks.PreToolUse = obj.hooks.PreToolUse.filter((e) => !JSON.stringify(e).includes(fname));
+    obj.hooks.PreToolUse.push(entry);
+    added++;
   }
   if (added) {
     fs.mkdirSync(path.dirname(p), { recursive: true });

package/lib/doctor.js

@@ -3,6 +3,7 @@ const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
 const { findProjectRoot, loadConfig, exists } = require("./core");
+const { contractHash, isShipped } = require("./gate");
 
 function cmdDoctor() {
   const ok = (b, label, fix) => console.log(`${b ? "OK  " : "FAIL"} ${label}${b || !fix ? "" : `——${fix}`}`);
@@ -46,20 +47,21 @@ function cmdDoctor() {
   const ids = exists(changesDir)
     ? fs.readdirSync(changesDir).filter((d) => { try { return fs.statSync(path.join(changesDir, d)).isDirectory(); } catch { return false; } })
     : [];
-  let confirmed = 0, stale = 0;
+  let confirmed = 0, stale = 0, shipped = 0;
   for (const id of ids) {
-    const cp = path.join(changesDir, id, "confirmed.json");
+    const cdir = path.join(changesDir, id);
+    if (isShipped(cdir)) { shipped++; continue; } // 已交付的不再体检
+    const cp = path.join(cdir, "confirmed.json");
     if (!exists(cp)) continue;
     confirmed++;
     try {
-      const at = Date.parse(JSON.parse(fs.readFileSync(cp, "utf8")).at) || 0;
-      for (const f of ["proposal.md", "test-cases.md"]) {
-        const p = path.join(changesDir, id, f);
-        if (exists(p) && fs.statSync(p).mtimeMs > at) { stale++; console.log(`FAIL 变更 ${id}: 确认后 ${f} 被修改——确认已失效，需重新 ai confirm`); bad++; break; }
+      const conf = JSON.parse(fs.readFileSync(cp, "utf8"));
+      if (conf.hash && conf.hash !== contractHash(cdir)) {
+        stale++; console.log(`FAIL 变更 ${id}: 契约内容在确认后被修改——确认已失效，需重新 ai confirm`); bad++;
       }
     } catch { console.log(`FAIL 变更 ${id}: confirmed.json 无效`); bad++; }
   }
-  console.log(`OK   变更: ${ids.length} 个（已确认 ${confirmed}，确认失效 ${stale}）`);
+  console.log(`OK   变更: ${ids.length} 个（进行中已确认 ${confirmed}，确认失效 ${stale}，已交付 ${shipped}）`);
 
   console.log(bad ? `\nDOCTOR_FAIL：${bad} 项需处理。` : "\nDOCTOR_OK：全部体检通过。");
   if (bad) process.exit(1);

package/lib/gate.js

@@ -103,7 +103,40 @@ function cmdCheck(args) {
   console.log("CHECK_PASSED：可向用户输出确认单（标注级别与判级理由）。");
 }
 
-// ── ai confirm：把"用户点头"变成可审计留痕（by/at/sha）────
+// 契约内容哈希：proposal + test-cases + specs 的内容指纹。
+// 用哈希而非 mtime 判定"确认后是否被改动"——git clone/换机器/checkout 会刷新
+// mtime 导致全体确认假失效（团队场景不可用），内容哈希两个方向都准。
+function contractHash(dir) {
+  const crypto = require("crypto");
+  const h = crypto.createHash("sha256");
+  const files = [];
+  for (const f of fs.readdirSync(dir, { recursive: true })) {
+    const rel = String(f).replace(/\\/g, "/");
+    const base = path.basename(rel);
+    const isContract = base === "proposal.md" || base === "test-cases.md" || rel.startsWith("specs");
+    const p = path.join(dir, rel);
+    if (isContract && p.endsWith(".md") && fs.statSync(p).isFile()) files.push(rel);
+  }
+  for (const rel of files.sort()) {
+    h.update(rel).update("\0").update(fs.readFileSync(path.join(dir, rel))).update("\0");
+  }
+  return h.digest("hex");
+}
+
+function isShipped(dir) {
+  return exists(path.join(dir, "shipped.json"));
+}
+
+// 活跃变更 = 目录存在且尚未交付
+function activeChanges(root) {
+  const base = path.join(root, ".ai", "changes");
+  if (!exists(base)) return [];
+  return fs.readdirSync(base).filter((d) => {
+    try { return fs.statSync(path.join(base, d)).isDirectory() && !isShipped(path.join(base, d)); } catch { return false; }
+  });
+}
+
+// ── ai confirm：把"用户点头"变成可审计留痕（by/at/sha/契约哈希）────
 function cmdConfirm(args) {
   const { id, root, dir } = requireChange(args, "用法: ai confirm <change-id>（用户确认变更单后执行）");
   const errors = runCheck(root, dir, id);
@@ -116,50 +149,88 @@ function cmdConfirm(args) {
     by: git("git config user.name") || process.env.USER || "unknown",
     at: new Date().toISOString(),
     sha: git("git rev-parse HEAD"),
+    hash: contractHash(dir),
   };
   fs.writeFileSync(path.join(dir, "confirmed.json"), JSON.stringify(record, null, 2) + "\n");
   console.log(`CONFIRM_OK：已留痕（by=${record.by}）。开始实现；proposal/test-cases 再改动需重新确认。`);
 }
 
-// 读取确认留痕；proposal/test-cases/specs 在确认后被改动 → 确认失效
+// 读取确认留痕；契约文件内容在确认后被改动 → 确认失效（按哈希，不受 mtime 影响）
 function requireFreshConfirm(dir, id) {
   const confPath = path.join(dir, "confirmed.json");
   if (!exists(confPath)) die(`变更未确认：向用户输出确认单，用户点头后运行 ai confirm ${id}`, 2);
-  let confAt = 0;
-  try { confAt = Date.parse(JSON.parse(read(confPath)).at) || 0; } catch { /* 落入下方校验 */ }
+  let conf = {};
+  try { conf = JSON.parse(read(confPath)); } catch { /* 落入下方校验 */ }
+  const confAt = Date.parse(conf.at) || 0;
   if (!confAt) die("confirmed.json 无效；重新运行 ai confirm", 2);
-  for (const f of fs.readdirSync(dir, { recursive: true })) {
-    const rel = String(f);
-    const p = path.join(dir, rel);
-    const base = path.basename(rel);
-    const isContract = base === "proposal.md" || base === "test-cases.md" || rel.startsWith("specs");
-    if (!isContract || !p.endsWith(".md") || !fs.statSync(p).isFile()) continue;
-    if (fs.statSync(p).mtimeMs > confAt) {
-      die(`确认已过期：${rel} 在确认后被修改；重新向用户确认并运行 ai confirm ${id}`, 2);
+  if (conf.hash) {
+    if (contractHash(dir) !== conf.hash) {
+      die(`确认已过期：proposal/test-cases/specs 在确认后被修改；重新向用户确认并运行 ai confirm ${id}`, 2);
     }
+  } else {
+    die(`confirmed.json 缺少契约哈希（旧版本产物）；重新运行 ai confirm ${id}`, 2);
   }
-  return confAt;
+  return conf;
+}
+
+// 密钥扫描：交付前扫描本变更引入的 diff（禁止密钥入库/外发是红线）。
+// 只用低误报的具体格式；关闭：config.json "secretScan": "off"
+const SECRET_RES = [
+  [/AKIA[0-9A-Z]{16}/, "AWS Access Key"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "私钥"],
+  [/gh[pos]_[A-Za-z0-9]{36}/, "GitHub Token"],
+  [/npm_[A-Za-z0-9]{36}/, "npm Token"],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/, "Slack Token"],
+  [/sk-[A-Za-z0-9_-]{32,}/, "API Key（sk- 前缀）"],
+  [/jdbc:[^\s'"]*password=[^\s'"&]+/i, "带密码的连接串"],
+];
+
+function changeDiff(root, sinceSha) {
+  const git = (cmd) => { try { return execSync(cmd, { cwd: root, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).toString(); } catch { return ""; } };
+  let out = git("git diff HEAD"); // 未提交部分
+  if (sinceSha) out += git(`git diff ${sinceSha} HEAD`); // 确认以来已提交部分
+  return out;
+}
+
+function scanSecrets(root, diffText) {
+  if ((loadConfig(root).secretScan || "") === "off") return [];
+  const hits = [];
+  for (const line of diffText.split("\n")) {
+    if (!line.startsWith("+") || line.startsWith("+++")) continue; // 只看新增行
+    for (const [re, label] of SECRET_RES) {
+      if (re.test(line)) hits.push(`${label}: ${line.slice(0, 80)}`);
+    }
+  }
+  return [...new Set(hits)];
 }
 
 // ── ai ship ──────────────────────────────────────────────
 function cmdShip(args) {
   const { id, root, dir } = requireChange(args, "用法: ai ship <change-id> [junit-报告目录...]");
   const { proposalText, casesText } = collect(dir);
-  const confAt = requireFreshConfirm(dir, id);
+  const conf = requireFreshConfirm(dir, id);
+  const confAt = Date.parse(conf.at);
   const rows = tcRows(casesText);
   const autoRows = rows.filter((l) => !MANUAL_RE.test(l));
 
+  // 红线：本变更引入的 diff 不得含密钥（入库即泄露；独立审查外发前也靠这道拦）
+  const diffText = changeDiff(root, conf.sha);
+  const secrets = scanSecrets(root, diffText);
+  if (secrets.length) {
+    secrets.forEach((s) => console.error(`SECRET_HIT: ${s}`));
+    die('diff 中检测到疑似密钥（见上）。移除或改用环境变量后重试；确属测试假数据可在 .ai/config.json 设 "secretScan": "off"', 2);
+  }
+
   if (autoRows.length === 0) {
     console.log("全部用例为手动验证：跳过 JUnit 报告核对，验收结果须逐条写入交付说明。");
   } else {
     const extraDirs = args.filter((a) => !a.startsWith("--") && a !== id);
-    // N-3 串号收口：存在多个变更时，全局报告目录无法证明"这是本变更的证据"——
-    // 必须用隔离目录（ai test <id> 自动生成）或显式传入报告路径
+    // N-3 串号收口：存在多个"活跃"变更时（已交付的不算——防止历史变更永久触发强制隔离），
+    // 全局报告目录无法证明"这是本变更的证据"——必须用隔离目录或显式传报告路径
     const scoped = path.join(root, "test-results", id);
-    const allChanges = fs.readdirSync(path.join(root, ".ai", "changes"))
-      .filter((d) => { try { return fs.statSync(path.join(root, ".ai", "changes", d)).isDirectory(); } catch { return false; } });
-    if (!extraDirs.length && !exists(scoped) && allChanges.length > 1) {
-      die(`存在多个变更（${allChanges.join(", ")}）：证据必须按变更隔离。运行 ai test ${id}（报告自动写入 test-results/${id}/），或显式传入报告目录`, 2);
+    const active = activeChanges(root);
+    if (!extraDirs.length && !exists(scoped) && active.length > 1) {
+      die(`存在多个进行中变更（${active.join(", ")}）：证据必须按变更隔离。运行 ai test ${id}（报告自动写入 test-results/${id}/），或显式传入报告目录`, 2);
     }
     const reportDirs = extraDirs.length ? extraDirs : findReportDirs(root, id);
     if (!reportDirs.length) die(`未找到 JUnit 报告目录；请先运行 ai test ${id}`, 2);
@@ -180,6 +251,14 @@ function cmdShip(args) {
     console.log(`EVIDENCE_OK：报告 ${parsed} 份，非手动用例 ${autoRows.length} 条全部有通过记录。`);
   }
 
+  // 声明诚实性软核验：实际改动 vs affected_files（只警告不拦——硬拦会造成
+  // "改文件→补声明→确认失效→重确认"的死循环式打扰；清单供用户与独立审查参考）
+  const undeclared = driftFiles(root, dir, conf.sha, proposalText);
+  if (undeclared.length) {
+    console.log(`注意：以下改动未在影响范围声明（软核验，不拦截）：`);
+    undeclared.forEach((f) => console.log(`  ? ${f}`));
+  }
+
   // 高风险提示（结构化判定，防 v1 的 grep 越界误报）
   if ((scopeItems(proposalText, "affected_tables") || []).length) {
     console.log("提示：本变更涉及数据库，建议在新会话用 .ai/templates/review-prompt.md 做一次独立审查。");
@@ -187,7 +266,29 @@ function cmdShip(args) {
     console.log("提示：本变更涉及支付/状态流，建议在新会话用 .ai/templates/review-prompt.md 做一次独立审查。");
   }
 
-  console.log("SHIP_GATES_PASSED：门禁全部通过。手动用例结果与残余风险写入交付说明。");
+  // 交付留痕：变更生命周期到此终结——guard-write 白名单与多变更隔离计数不再包含它
+  fs.writeFileSync(path.join(dir, "shipped.json"),
+    JSON.stringify({ at: new Date().toISOString(), evidence: autoRows.length ? "junit" : "manual" }, null, 2) + "\n");
+  console.log("SHIP_GATES_PASSED：门禁全部通过（已写入 shipped.json）。手动用例结果与残余风险写入交付说明。");
+}
+
+// 确认以来实际改动、但未在 affected_files 声明的业务文件
+function driftFiles(root, dir, sinceSha, proposalText) {
+  const git = (cmd) => { try { return execSync(cmd, { cwd: root, stdio: ["ignore", "pipe", "ignore"] }).toString(); } catch { return ""; } };
+  let names = git("git diff --name-only HEAD");
+  if (sinceSha) names += git(`git diff --name-only ${sinceSha} HEAD`);
+  const changed = [...new Set(names.split("\n").map((s) => s.trim()).filter(Boolean))];
+  if (!changed.length) return [];
+  const declared = scopeItems(proposalText, "affected_files") || [];
+  const FREE = [/\.md$/i, /(^|\/)\.(ai|claude|workbuddy|github)\//, /(^|\/)(tests?|__tests__|test-results)\//, /\.(test|spec)\.[jt]sx?$/, /Test\.(java|kt|php)$/, /_test\.go$/];
+  return changed.filter((f) => {
+    if (FREE.some((re) => re.test(f))) return false;
+    return !declared.some((e) => {
+      const d = e.replace(/^\.\//, "");
+      if (d.endsWith("/")) return f.startsWith(d) || f.includes("/" + d);
+      return f === d || f.endsWith("/" + d) || d.endsWith("/" + f) || f.endsWith(d);
+    });
+  });
 }
 
-module.exports = { cmdCheck, cmdConfirm, cmdShip };
+module.exports = { cmdCheck, cmdConfirm, cmdShip, contractHash, activeChanges, isShipped };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightliu/ai-control",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "AGENTS.md 标准之上的中文全栈 AI 工程控制层：规格先行、DB 两阶段确认、证据验收。支持 Codex / Claude Code / Cursor / Kimi / Qoder / WorkBuddy。",
   "bin": {
     "ai": "bin/ai.js"

package/payload/hooks/guard-write.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-// Claude Code PreToolUse 钩子（Write/Edit）：把“change 确认前禁止写业务代码”从
-// 提示词约束前移为写入瞬间的机械拦截——违规不再是“写完被 check 打回”，而是第一行就写不进去。
+// Claude Code PreToolUse 钩子（Write/Edit）：把"change 确认前禁止写业务代码"从
+// 提示词约束前移为写入瞬间的机械拦截。
 // 协议：stdin 收 JSON；exit 0 放行，exit 2 拦截（stderr 反馈给 Claude）。
-// 原则：fail-open——解析失败/结构异常一律放行；只拦最明确的两种违规：
-//   1) 存在变更单但一个都没确认 → 禁止写业务代码（文档/测试/.ai 内除外）
-//   2) 已有确认的变更 → 业务代码路径必须落在某个已确认变更的 affected_files 内
+// 原则：
+//   - fail-open——解析失败/结构异常一律放行；
+//   - 只看"活跃"变更（已 shipped 的不算——防止白名单随历史变更膨胀）；
+//   - 简单任务通道——未确认草稿只锁"它自己声明要改的文件"，无关小改不拦；
+//   - 已确认变更实现期间，业务代码写入须落在其声明的影响范围内。
 // 逃生阀：AI_CONTROL_HOOKS=off，或 .ai/config.json 里 "hooks": "off"。
 
 const fs = require("fs");
@@ -22,10 +24,50 @@ process.stdin.on("end", () => {
   }
 });
 
+// 项目根：Claude Code 注入的 CLAUDE_PROJECT_DIR 优先；否则从 cwd 向上找 .ai/
+// （子目录启动 Claude 时 cwd 不是项目根，相对路径会失效——B 修复）
+function findRoot() {
+  if (process.env.CLAUDE_PROJECT_DIR && fs.existsSync(path.join(process.env.CLAUDE_PROJECT_DIR, ".ai"))) {
+    return process.env.CLAUDE_PROJECT_DIR;
+  }
+  let dir = process.cwd();
+  while (true) {
+    if (fs.existsSync(path.join(dir, ".ai"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function affectedFiles(changesDir, id) {
+  try {
+    const text = fs.readFileSync(path.join(changesDir, id, "proposal.md"), "utf8");
+    const m = text.match(/^[ \t]*affected_files:[ \t]*([^\n]*)\n?((?:[ \t]*-[ \t]*[^\n]*\n?)*)/m);
+    if (!m) return [];
+    const items = [];
+    if (m[1] && m[1].trim()) items.push(m[1].trim());
+    for (const l of (m[2] || "").split("\n")) {
+      const v = l.replace(/^[ \t]*-[ \t]*/, "").replace(/[`'"]/g, "").trim();
+      if (v && !/^(none|无|暂无|n\/a)$/i.test(v)) items.push(v);
+    }
+    return items;
+  } catch { return []; }
+}
+
+function matches(rel, entries) {
+  const norm = (s) => s.replace(/^\.\//, "").replace(/\\/g, "/");
+  return entries.some((e) => {
+    const d = norm(e);
+    if (d.endsWith("/")) return rel.startsWith(d) || rel.includes("/" + d);
+    return rel === d || rel.endsWith("/" + d) || d.endsWith("/" + rel) || rel.endsWith(d);
+  });
+}
+
 function main(input) {
   const fp = (input.tool_input || {}).file_path || (input.tool_input || {}).notebook_path || "";
   if (!fp) process.exit(0);
-  const root = process.cwd();
+  const root = findRoot();
+  if (!root) process.exit(0);
   try {
     if ((JSON.parse(fs.readFileSync(path.join(root, ".ai", "config.json"), "utf8")).hooks || "") === "off") process.exit(0);
   } catch { /* 无配置则默认开启 */ }
@@ -46,47 +88,41 @@ function main(input) {
   const changesDir = path.join(root, ".ai", "changes");
   let ids = [];
   try {
-    ids = fs.readdirSync(changesDir).filter((d) => fs.statSync(path.join(changesDir, d)).isDirectory());
-  } catch { process.exit(0); } // 未安装/无变更目录：不拦（契约仍然管）
+    ids = fs.readdirSync(changesDir).filter((d) => {
+      try {
+        return fs.statSync(path.join(changesDir, d)).isDirectory()
+          && !fs.existsSync(path.join(changesDir, d, "shipped.json")); // 已交付不再约束
+      } catch { return false; }
+    });
+  } catch { process.exit(0); }
   if (!ids.length) process.exit(0);
 
   const confirmed = ids.filter((id) => fs.existsSync(path.join(changesDir, id, "confirmed.json")));
-  if (!confirmed.length) {
-    console.error(
-      `[ai-control] 已拦截：存在变更单（${ids.join(", ")}）但均未确认。` +
-      `change 确认前禁止写业务代码——先 ai check 通过、向用户输出确认单，用户点头后 ai confirm <id> 再实现。`
-    );
-    process.exit(2);
-  }
+  const drafts = ids.filter((id) => !confirmed.includes(id));
 
-  // 汇总已确认变更声明的影响文件
-  const declared = [];
-  for (const id of confirmed) {
-    try {
-      const text = fs.readFileSync(path.join(changesDir, id, "proposal.md"), "utf8");
-      const m = text.match(/^[ \t]*affected_files:[ \t]*([^\n]*)\n?((?:[ \t]*-[ \t]*[^\n]*\n?)*)/m);
-      if (!m) continue;
-      if (m[1] && m[1].trim()) declared.push(m[1].trim());
-      for (const l of (m[2] || "").split("\n")) {
-        const v = l.replace(/^[ \t]*-[ \t]*/, "").replace(/[`'"]/g, "").trim();
-        if (v && !/^(none|无|暂无|n\/a)$/i.test(v)) declared.push(v);
-      }
-    } catch { /* 单个变更读取失败不影响其他 */ }
+  // 未确认草稿只锁"它自己声明要改的文件"——防 AI 先实现后确认；
+  // 无关文件放行（简单任务通道：改个配置/错别字不该被烂尾草稿连坐）
+  for (const id of drafts) {
+    if (matches(rel, affectedFiles(changesDir, id))) {
+      console.error(
+        `[ai-control] 已拦截：${rel} 是变更 ${id} 声明要改的文件，但该变更尚未确认。` +
+        `先 ai check 通过、向用户输出确认单，用户点头后由用户运行 ai confirm ${id}，再开始实现。`
+      );
+      process.exit(2);
+    }
   }
-  if (!declared.length) process.exit(0); // 声明为空/异常：fail-open
 
-  const norm = (s) => s.replace(/^\.\//, "").replace(/\\/g, "/");
-  const ok = declared.some((e) => {
-    const d = norm(e);
-    if (d.endsWith("/")) return rel.startsWith(d) || rel.includes("/" + d);
-    return rel === d || rel.endsWith("/" + d) || d.endsWith("/" + rel) || rel.endsWith(d);
-  });
-  if (!ok) {
-    console.error(
-      `[ai-control] 已拦截：${rel} 不在任何已确认变更的 affected_files 内` +
-      `（已确认: ${confirmed.join(", ")}）。禁止修改无关文件；确需修改则更新 proposal 影响范围并重新经用户确认（ai confirm）。`
-    );
-    process.exit(2);
+  // 已确认变更实现期间：业务代码写入须落在某个已确认变更的影响范围内
+  if (confirmed.length) {
+    const declared = confirmed.flatMap((id) => affectedFiles(changesDir, id));
+    if (!declared.length) process.exit(0); // 声明为空/异常：fail-open
+    if (!matches(rel, declared)) {
+      console.error(
+        `[ai-control] 已拦截：${rel} 不在任何进行中变更的 affected_files 内（进行中: ${confirmed.join(", ")}）。` +
+        `属本变更的改动请更新 proposal 影响范围并重新经用户确认；与变更无关的简单任务请先交付当前变更，或让用户以 AI_CONTROL_HOOKS=off 临时放行。`
+      );
+      process.exit(2);
+    }
   }
   process.exit(0);
 }