@erzhe/harness-kit 0.1.0 → 0.1.2

package/README.md

@@ -1,70 +1,131 @@
 # @erzhe/harness-kit
 
-> AI-friendly repo harness —— 把工程知识变成 agent 可消费的**契约层**。
+> 给 Agent 发一句话，让它帮你把仓库变成 AI 友好的。
 
-一份 `.agents/manifest.yaml` 作为单一事实源，生成各家 agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用**门禁**保证不变量、对外契约和文档不漂移。让不同的人、不同的机器上的 agent，构建出**一模一样的范式**。
+harness-kit 把仓库的工程知识（这是什么、怎么跑、什么不能破、改东西看哪）沉淀成一份 `.agents/manifest.yaml`，然后自动生成各家 Agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用门禁保证它们始终一致。
 
-> 包名 `@erzhe/harness-kit`，安装后命令行工具叫 **`harness-kit`**。
+---
 
-## 为什么
+## 最快上手
 
-传统工程化（脚手架 / lint / CI）是**面向过去、面向人**的。Agent 需要的是显式、结构化、可机器消费的知识：这个仓库是什么、能跑什么、什么绝不能破、改动该看哪、哪些验证不了。`harness-kit` 把这些沉淀进 manifest，再确定性地生成与校验。
+在**任意仓库**里，把这句话丢给你的 Agent（Cursor / Claude Code / Codex 通用）：
 
-## 安装
-
-```bash
-npm i -g @erzhe/harness-kit      # 或 pnpm add -g / 直接 npx @erzhe/harness-kit
-harness-kit --help
+```
+Onboard 本仓库到 harness-kit：跑 npx -y @erzhe/harness-kit@latest onboard，然后严格按输出执行。
 ```
 
-## 命令
+就这一句。Agent 会：
+
+1. 拉取最新版的 onboard skill
+2. 扫描你的仓库（读 README、package.json、目录结构…）
+3. 逐块跟你确认着填 `.agents/manifest.yaml`
+4. 跑 `sync` / `doctor` / `verify` 直到全绿
+
+全程走 `npx`，不往机器上装任何全局东西；你一发新版，所有人下次执行就用上了。
+
+---
+
+## 初始化后你得到什么
 
 ```
-harness-kit init             # 铺 .agents/ 骨架 + starter manifest
-harness-kit sync             # manifest -> AGENTS.md / CLAUDE.md / Cursor rules / routing / modules
-harness-kit doctor           # 开发态体检：补全度 / 引用路径 / 漂移 / 新鲜度 / 体量预算
-harness-kit verify           # 门禁（CI）：跑不变量 + 契约 + 漂移，列出 GAPS，失败非 0 退出
-harness-kit accept-contract  # 一次预期的接口变更后，记录新的契约指纹为基线
+你的仓库/
+  AGENTS.md                    ← [生成] 跨工具入口，Agent 每次会话必读
+  CLAUDE.md                    ← [生成] Claude Code 入口
+  .cursor/rules/               ← [生成] Cursor 规则
+  .agents/
+    manifest.yaml              ← 你维护的唯一真相源
+    knowledge/                 ← Agent 从代码推不出来的知识（领域、约定、决策）
+    contracts/                 ← 对外接口的契约基线
+    playbooks/                 ← 可复用的工作流（SKILL.md）
+    routing.md                 ← [生成] 按改动类型导航：改 UI 看哪、加接口看哪
+    modules.md                 ← [生成] 模块卡：每个子系统的职责/入口/坑
 ```
 
-## 心智模型
+以后改工程知识 → 编辑 `manifest.yaml` → `harness-kit sync`。别手改生成物。
+
+---
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `harness-kit onboard` | 打印 onboard skill 给 Agent（配合 npx，永远最新、零安装） |
+| `harness-kit init` | 铺 `.agents/` 骨架 + 空白 manifest |
+| `harness-kit sync` | manifest → 生成 AGENTS.md / CLAUDE.md / Cursor rules / routing / modules |
+| `harness-kit doctor` | 体检：完整性 / 路径引用 / 漂移 / 新鲜度 / 体量预算 |
+| `harness-kit verify` | 门禁：跑不变量 + 契约 + 漂移，列出 GAPS，失败非 0 退出 |
+| `harness-kit accept-contract` | 有意变更接口后，记录新的契约指纹为基线 |
+| `harness-kit install-hooks` | 装 git 钩子：pre-commit 自动 sync + pre-push verify 拦漂移 |
+
+所有命令都支持 `-C <dir>` 指定目标仓库（默认当前目录）。
+
+---
+
+## 它解决什么问题
+
+传统工程化（脚手架 / lint / CI）是**面向人、面向过去**的。Agent 需要的是显式、结构化、可机器消费的知识：
+
+- **这是什么** → `identity`（name / summary / scope）
+- **怎么跑** → `capabilities`（setup / build / test / dev…）
+- **什么绝不能破** → `invariants`（声明式正则门禁）+ `contracts`（接口指纹基线）
+- **改东西看哪** → `routing`（按改动类型导航）+ `modules`（模块卡）
+- **哪些验证不了** → `GAPS`（诚实标注，绝不谎报）
+
+harness-kit 把这些沉淀进 manifest，再确定性地生成与校验。
+
+---
+
+## 工作原理
 
 ```
-.agents/manifest.yaml   (你 + agent 维护的唯一源)
-        |
+.agents/manifest.yaml   (你 + Agent 维护的唯一源)
+        │
    harness-kit sync     (确定性生成，勿手改产物)
-        v
+        ▼
 AGENTS.md / CLAUDE.md / .cursor/rules / .agents/routing.md / .agents/modules.md
-        |
-   harness-kit verify   (门禁：不变量 enforcement + 契约 snapshot + 生成物/知识漂移)
-        v
-   exit 0 / 非 0  +  诚实的 GAPS 清单（查不了的东西绝不谎报）
+        │
+   harness-kit verify   (门禁：不变量 + 契约 + 漂移)
+        ▼
+   exit 0 / 非 0  +  诚实的 GAPS 清单
 ```
 
-- **不变量**：声明式正则 `enforcement`（确定性、无 LLM），或标 `manual`。
-- **契约**：协议无关——`check`（跑仓库自带工具看退出码）或 `snapshot`（打印接口指纹 → CLI 存基线并 diff）。
-- **新鲜度**：知识条目 / 模块卡 `binds` 源文件哈希，代码一动就告警，无需人肉维护日期。
-- **GAPS**：打包 / 真网络 / 生产上传等本地验证不了的，`verify` 显式列出，绝不假装通过。
+- **不变量**：声明式正则 `enforcement`（确定性、无 LLM），或标 `manual`
+- **契约**：`snapshot` 打印接口指纹 → CLI 存基线并 diff（协议无关）
+- **新鲜度**：知识条目 `binds` 源文件哈希，代码一动就告警
+- **GAPS**：打包 / 真网络 / 生产上传等本地验证不了的，显式列出
 
-## 让 agent 来配置：onboard skill
+---
 
-手写 manifest 门槛高，但对 agent 是绝配。随包附带的 [`skills/erzhe-harness-init`](skills/erzhe-harness-init/SKILL.md) 引导 agent 做仓库考古、逐块跟你确认着填 manifest、再跑 `sync/doctor/verify` 到绿。把它软链到 `~/.cursor/skills/` 或 `~/.claude/skills/` 即可被发现。
+## 让 Agent 自动触发（可选）
 
-## 文档
+上面的"最快上手"是**显式调用**——你每次说"onboard 本仓库"，Agent 才会做。如果你想让某个 Agent **自动识别**"该给仓库接 harness-kit"，可以把 skill 软链进它的 skill 目录：
+
+```bash
+# Cursor
+ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.cursor/skills/
+
+# Claude Code
+ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.claude/skills/
+```
+
+这样当用户说"给这个仓库配置 harness"时，Agent 会自动找到并执行这个 skill。
 
-- [`SPEC-v0.md`](SPEC-v0.md) —— manifest schema + 生成/校验契约（当前 v0.2）
-- [`DESIGN.md`](DESIGN.md) —— 设计决策、调研与决策日志
+---
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm typecheck
-pnpm test        # node:test + tsx，核心逻辑单测
-pnpm build       # esbuild 打包成 dist/harness-kit.cjs 单文件可执行
-pnpm exec tsx src/cli.ts verify --repo .   # 开发态直接跑，且自托管验证本仓
+pnpm typecheck          # tsc --noEmit
+pnpm test               # node:test + tsx
+pnpm build              # esbuild → dist/harness-kit.cjs
+pnpm exec tsx src/cli.ts verify --repo .   # 自托管验证
 ```
 
+## 文档
+
+- [`SPEC-v0.md`](SPEC-v0.md) — manifest schema + 生成/校验契约
+
 ## License
 
 MIT © [MeCKodo (二哲)](https://erzhe.me/)

package/SPEC-v0.md

@@ -165,7 +165,9 @@ generate:
 5. 新鲜度：`knowledge.binds` 的源文件 hash 变了 → 报 drift；`invariants` 里 `manual:true` 的计入"待补门禁"技术债并给出数量。
 6. **AGENTS.md 体量预算**：生成的 `AGENTS.md` 超过 ~150 行 / ~700 词告警。渐进式披露——入口只指路，细节放 `.agents/` 按需加载，绝不让 Agent 读不完。
 
-`harness verify`（CI 门禁，全确定性）= 所有 `invariants` 的 `enforcement`/`check` + `contracts.check` + `capabilities.verify` + "生成物无漂移"。任一失败即 fail。
+`harness-kit verify`（CI 门禁，全确定性）= 所有 `invariants` 的 `enforcement`/`check` + `contracts` 的 `check`/`snapshot` + "生成物无漂移"。任一失败即 fail。
+
+> **`verify` 不执行任何 `capabilities`**。`capabilities.verify` 只是给人 / agent 看的"如何验证本仓"指针；若真去执行会与自身无限递归。声明为 `mutating` / `background` 的 capability 一律进 GAPS（诚实标注"未在门禁里跑"），不实跑。所以放心声明 `setup: rush install`、`build: go build` 等——`verify` 不会在无网 / 无依赖环境里去跑它们。
 
 **契约校验（v0.2，协议无关）**：契约的破坏检测有两条互补路径，CLI **不理解任何协议语义**，只当调度器 + 基线框架：
 - `check`：仓库自带的破坏检测工具（HTTP → `oasdiff`；gRPC/protobuf → `buf breaking`；库 → `api-extractor`；CLI → 自写脚本），exit 0 = 兼容。CLI 只 `execSync` 看退出码。

package/dist/harness-kit.cjs

@@ -11214,11 +11214,11 @@ var require_out = __commonJS({
       async.read(path2, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports2.stat = stat;
-    function statSync(path2, optionsOrSettings) {
+    function statSync3(path2, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
       return sync.read(path2, settings);
     }
-    exports2.statSync = statSync;
+    exports2.statSync = statSync3;
     function getSettings(settingsOrOptions = {}) {
       if (settingsOrOptions instanceof settings_1.default) {
         return settingsOrOptions;
@@ -11883,41 +11883,41 @@ var require_queue = __commonJS({
       queue.drained = drained;
       return queue;
       function push(value) {
-        var p = new Promise(function(resolve2, reject) {
+        var p = new Promise(function(resolve3, reject) {
           pushCb(value, function(err2, result) {
             if (err2) {
               reject(err2);
               return;
             }
-            resolve2(result);
+            resolve3(result);
           });
         });
         p.catch(noop);
         return p;
       }
       function unshift(value) {
-        var p = new Promise(function(resolve2, reject) {
+        var p = new Promise(function(resolve3, reject) {
           unshiftCb(value, function(err2, result) {
             if (err2) {
               reject(err2);
               return;
             }
-            resolve2(result);
+            resolve3(result);
           });
         });
         p.catch(noop);
         return p;
       }
       function drained() {
-        var p = new Promise(function(resolve2) {
+        var p = new Promise(function(resolve3) {
           process.nextTick(function() {
             if (queue.idle()) {
-              resolve2();
+              resolve3();
             } else {
               var previousDrain = queue.drain;
               queue.drain = function() {
                 if (typeof previousDrain === "function") previousDrain();
-                resolve2();
+                resolve3();
                 queue.drain = previousDrain;
               };
             }
@@ -12403,9 +12403,9 @@ var require_stream3 = __commonJS({
         });
       }
       _getStat(filepath) {
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           this._stat(filepath, this._fsStatSettings, (error, stats) => {
-            return error === null ? resolve2(stats) : reject(error);
+            return error === null ? resolve3(stats) : reject(error);
           });
         });
       }
@@ -12429,10 +12429,10 @@ var require_async5 = __commonJS({
         this._readerStream = new stream_1.default(this._settings);
       }
       dynamic(root, options) {
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           this._walkAsync(root, options, (error, entries) => {
             if (error === null) {
-              resolve2(entries);
+              resolve3(entries);
             } else {
               reject(error);
             }
@@ -12442,10 +12442,10 @@ var require_async5 = __commonJS({
       async static(patterns, options) {
         const entries = [];
         const stream = this._readerStream.static(patterns, options);
-        return new Promise((resolve2, reject) => {
+        return new Promise((resolve3, reject) => {
           stream.once("error", reject);
           stream.on("data", (entry) => entries.push(entry));
-          stream.once("end", () => resolve2(entries));
+          stream.once("end", () => resolve3(entries));
         });
       }
     };
@@ -16471,7 +16471,7 @@ function useColor() {
 var program = new Command();
 
 // src/cli.ts
-var import_node_path11 = require("node:path");
+var import_node_path13 = require("node:path");
 
 // src/commands/init.ts
 var import_node_fs3 = require("node:fs");
@@ -16485,8 +16485,12 @@ function sha256(input) {
   return (0, import_node_crypto.createHash)("sha256").update(input).digest("hex");
 }
 function hashFile(absPath) {
-  if (!(0, import_node_fs2.existsSync)(absPath)) return null;
-  return sha256((0, import_node_fs2.readFileSync)(absPath));
+  try {
+    if (!(0, import_node_fs2.statSync)(absPath).isFile()) return null;
+    return sha256((0, import_node_fs2.readFileSync)(absPath));
+  } catch {
+    return null;
+  }
 }
 function readText(absPath) {
   return (0, import_node_fs2.existsSync)(absPath) ? (0, import_node_fs2.readFileSync)(absPath, "utf8") : null;
@@ -16841,6 +16845,7 @@ function syncCmd(repo) {
 }
 
 // src/commands/doctor.ts
+var import_fast_glob = __toESM(require_out4(), 1);
 var import_node_fs5 = require("node:fs");
 var import_node_path7 = require("node:path");
 var AGENTS_MAX_LINES = 150;
@@ -16859,6 +16864,18 @@ function doctorCmd(repo) {
       warn(i.msg);
     }
   }
+  for (const inv of m.invariants ?? []) {
+    if (!inv.enforcement) continue;
+    const globs = inv.enforcement.path_glob?.length ? inv.enforcement.path_glob : ["**/*"];
+    const n = import_fast_glob.default.sync(globs, {
+      cwd: repo,
+      onlyFiles: true,
+      dot: false,
+      ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
+    }).length;
+    if (n === 0)
+      warn(`invariant ${inv.id}: enforcement path_glob matches 0 files \u2014 passes without checking anything (wrong path_glob for this repo layout?)`);
+  }
   info("\n2) Referenced paths");
   const checkPath = (rel, label) => {
     if ((0, import_node_fs5.existsSync)((0, import_node_path7.join)(repo, ".agents", rel))) ok(`${label}: ${rel}`);
@@ -16867,19 +16884,24 @@ function doctorCmd(repo) {
       problems++;
     }
   };
-  const checkRepoPath = (rel, label) => {
-    if ((0, import_node_fs5.existsSync)((0, import_node_path7.join)(repo, rel))) ok(`${label}: ${rel}`);
-    else {
-      warn(`${label} points at a missing path: ${rel}`);
+  const checkRepoPath = (rel, label, wantFile = false) => {
+    const abs = (0, import_node_path7.join)(repo, rel);
+    if (!(0, import_node_fs5.existsSync)(abs)) {
+      err(`${label} points at a missing path: ${rel}`);
       problems++;
-    }
+    } else if (wantFile && (0, import_node_fs5.statSync)(abs).isDirectory()) {
+      warn(`${label}: ${rel} is a directory \u2014 entry/binds should be a file (freshness hashes file content)`);
+    } else ok(`${label}: ${rel}`);
   };
-  for (const k of m.knowledge ?? []) checkPath(k.path, "knowledge");
+  for (const k of m.knowledge ?? []) {
+    checkPath(k.path, "knowledge");
+    for (const b of new Set(k.binds ?? [])) checkRepoPath(b, `knowledge "${k.path}" binds`, true);
+  }
   if (m.playbooks?.dir) checkPath(m.playbooks.dir, "playbooks");
   for (const r of m.routing ?? [])
     for (const p of /* @__PURE__ */ new Set([...r.read ?? [], ...r.entry ?? []])) checkRepoPath(p, `routing "${r.when}"`);
   for (const mod of m.modules ?? [])
-    for (const p of new Set(mod.entry ?? [])) checkRepoPath(p, `module ${mod.name}`);
+    for (const p of new Set(mod.entry ?? [])) checkRepoPath(p, `module ${mod.name}`, true);
   info("\n3) Generated files drift");
   for (const [rel, content] of renderTargets(m)) {
     const cur = readText((0, import_node_path7.join)(repo, rel));
@@ -16961,13 +16983,13 @@ function writeBaseline(repo, id, content) {
 }
 
 // src/enforce.ts
-var import_fast_glob = __toESM(require_out4(), 1);
+var import_fast_glob2 = __toESM(require_out4(), 1);
 var import_node_fs6 = require("node:fs");
 var import_node_path9 = require("node:path");
 var DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/.agents/map/**"];
 function runEnforcement(repo, invId, e) {
   const globs = e.path_glob?.length ? e.path_glob : ["**/*"];
-  const files = import_fast_glob.default.sync(globs, {
+  const files = import_fast_glob2.default.sync(globs, {
     cwd: repo,
     onlyFiles: true,
     dot: false,
@@ -17142,6 +17164,117 @@ function acceptContractCmd(repo, id) {
   return problems ? 1 : 0;
 }
 
+// src/commands/install-hooks.ts
+var import_node_child_process4 = require("node:child_process");
+var import_node_fs7 = require("node:fs");
+var import_node_path11 = require("node:path");
+var MARK = "harness-kit-managed-hook";
+function hooksDir(repo) {
+  const out = (0, import_node_child_process4.execSync)("git rev-parse --git-path hooks", { cwd: repo, encoding: "utf8" }).trim();
+  return (0, import_node_path11.resolve)(repo, out);
+}
+function preCommit() {
+  return `#!/bin/sh
+# ${MARK} (pre-commit): regenerate agent files from the manifest and stage them,
+# so generated docs never drift from .agents/manifest.yaml.
+# Reset with \`harness-kit install-hooks --force\`; delete this file to remove.
+[ -f .agents/manifest.yaml ] || exit 0
+HK="\${HARNESS_KIT_CMD:-npx -y @erzhe/harness-kit@latest}"
+if ! $HK sync --repo . >/dev/null; then
+  echo "harness-kit: sync failed (run \\\`$HK sync\\\` to see why)" >&2
+  exit 1
+fi
+git add AGENTS.md CLAUDE.md .cursor/rules .agents >/dev/null 2>&1 || true
+exit 0
+`;
+}
+function prePush() {
+  return `#!/bin/sh
+# ${MARK} (pre-push): block the push when the agent context has drifted from code.
+# Bypass once with \`git push --no-verify\`.
+[ -f .agents/manifest.yaml ] || exit 0
+HK="\${HARNESS_KIT_CMD:-npx -y @erzhe/harness-kit@latest}"
+if ! $HK verify --repo .; then
+  echo "" >&2
+  echo "harness-kit: verify failed \u2014 agent context drifted from code." >&2
+  echo "  self-heal: run an agent with \\\`$HK onboard\\\` and follow its Maintenance section," >&2
+  echo "  then review the diff. Bypass once with \\\`git push --no-verify\\\`." >&2
+  exit 1
+fi
+exit 0
+`;
+}
+function installHooksCmd(repo, force = false) {
+  let dir;
+  try {
+    dir = hooksDir(repo);
+  } catch {
+    err("not a git repo (git rev-parse failed) \u2014 run inside a git working tree");
+    return 1;
+  }
+  const targets = [
+    ["pre-commit", preCommit()],
+    ["pre-push", prePush()]
+  ];
+  for (const [name, body] of targets) {
+    const p = (0, import_node_path11.join)(dir, name);
+    if ((0, import_node_fs7.existsSync)(p) && !force) {
+      const cur = (0, import_node_fs7.readFileSync)(p, "utf8");
+      if (!cur.includes(MARK)) {
+        warn(`${name} exists and isn't harness-kit-managed \u2014 skipped (use --force to overwrite)`);
+        continue;
+      }
+    }
+    writeText(p, body);
+    (0, import_node_fs7.chmodSync)(p, 493);
+    ok(`installed ${name}`);
+  }
+  info(`
+Hooks written to ${dir}`);
+  info("pre-commit: regenerates agent files from the manifest and stages them.");
+  info("pre-push:   runs `harness-kit verify` and blocks on drift (bypass: git push --no-verify).");
+  info("override the CLI it calls with env HARNESS_KIT_CMD (e.g. for local dev).");
+  return 0;
+}
+
+// src/commands/onboard.ts
+var import_node_fs8 = require("node:fs");
+var import_node_path12 = require("node:path");
+var import_node_url = require("node:url");
+var import_meta = {};
+function moduleDir() {
+  if (typeof __dirname !== "undefined" && __dirname) return __dirname;
+  return (0, import_node_path12.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+}
+var HERE = moduleDir();
+var SKILL_REL = "skills/erzhe-harness-init/SKILL.md";
+var META = `<!-- harness-kit onboard -->
+You are an AI agent onboarding the CURRENT repository to harness-kit.
+Follow the skill below verbatim. Run every harness-kit command through
+\`npx -y @erzhe/harness-kit@latest <cmd>\` \u2014 always the latest version, no global install.
+Do not fabricate: confirm uncertain fields with the user, and report honest GAPS.
+
+---
+
+`;
+function resolveSkill() {
+  for (const up of ["..", (0, import_node_path12.join)("..", "..")]) {
+    const p = (0, import_node_path12.join)(HERE, up, SKILL_REL);
+    if ((0, import_node_fs8.existsSync)(p)) return p;
+  }
+  return null;
+}
+function onboardCmd() {
+  const p = resolveSkill();
+  if (!p) {
+    err(`bundled skill not found (${SKILL_REL})`);
+    return 1;
+  }
+  process.stdout.write(META);
+  process.stdout.write((0, import_node_fs8.readFileSync)(p, "utf8"));
+  return 0;
+}
+
 // src/cli.ts
 function guard(fn) {
   try {
@@ -17153,13 +17286,15 @@ function guard(fn) {
   }
 }
 var program2 = new Command();
-program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.0");
-var repoOf = (o) => (0, import_node_path11.resolve)(o.repo);
+program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.2");
+var repoOf = (o) => (0, import_node_path13.resolve)(o.repo);
 program2.command("init").description("scaffold .agents/ skeleton + starter manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--name <name>", "project name", "my-project").option("--force", "overwrite existing manifest", false).action((o) => guard(() => initCmd(repoOf(o), o.name, o.force)));
 program2.command("sync").description("generate tool files (AGENTS.md, CLAUDE.md, .cursor rules) from manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => syncCmd(repoOf(o))));
 program2.command("doctor").description("dev-time health check: completeness, drift, freshness, tech debt").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => doctorCmd(repoOf(o))));
 program2.command("verify").description("CI gate: run enforceable invariants + contracts + drift; nonzero on failure").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => verifyCmd(repoOf(o))));
 program2.command("accept-contract").description("record current contract fingerprint(s) as the accepted baseline (after an intended change)").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--id <id>", "only this contract (default: all with a snapshot command)").action((o) => guard(() => acceptContractCmd(repoOf(o), o.id)));
+program2.command("install-hooks").description("install git hooks: pre-commit auto-sync + pre-push verify (drift gate)").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--force", "overwrite existing hooks", false).action((o) => guard(() => installHooksCmd(repoOf(o), o.force)));
+program2.command("onboard").description("print the erzhe-harness-init skill for an agent to follow (use via npx, always latest)").action(() => guard(() => onboardCmd()));
 program2.parseAsync();
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erzhe/harness-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "AI-friendly repo harness: a manifest.yaml single source of truth that generates AGENTS.md / CLAUDE.md / Cursor rules and enforces invariants, contracts and drift via `harness-kit verify`.",
   "keywords": [
@@ -41,9 +41,10 @@
   },
   "scripts": {
     "harness": "tsx src/cli.ts",
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --target=node18 --outfile=dist/harness-kit.cjs && chmod +x dist/harness-kit.cjs",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --target=node18 --log-override:empty-import-meta=silent --outfile=dist/harness-kit.cjs && chmod +x dist/harness-kit.cjs",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test test/*.test.ts",
+    "test:repos": "bash scripts/regression.sh",
     "prepare": "pnpm build"
   },
   "dependencies": {

package/skills/erzhe-harness-init/SKILL.md

@@ -13,11 +13,11 @@ CLI 只负责机械骨架 + 确定性门禁；**理解仓库、把隐性知识
 
 按可用性择一，后续统一用 `harness-kit` 指代（包名 `@erzhe/harness-kit`，bin 是 `harness-kit`）：
 
+- **推荐（零安装、永远最新）**：`npx -y @erzhe/harness-kit@latest`
 - 已全局安装：`harness-kit`
-- 未安装、临时用：`npx @erzhe/harness-kit`
 - 在 harness-kit 仓内开发：`pnpm exec tsx src/cli.ts`
 
-先跑 `harness-kit --help` 确认可用。
+先跑一次 `--help` 确认可用（如 `npx -y @erzhe/harness-kit@latest --help`）。全程用同一种方式，别混用版本。
 
 ## 1. 铺骨架（若还没有 .agents/）
 
@@ -40,9 +40,9 @@ harness-kit init --repo .
 1. **identity**：读 `README` / `package.json` / 顶层目录。填 `name`、一句话 `summary`、`scope_in` / `scope_out`（哪些该改、哪些别碰）、`upstream` / `downstream`。
 2. **capabilities**：从 `package.json` scripts、`Makefile`、`justfile`、CI 配置推断常用命令（setup / build / test / dev / lint / release）。给 `run`；长驻的标 `background: true`，有副作用的标 `mutating: true`。
 3. **environment**：从 `.env.example` / README 抓关键环境变量。危险的标 `secret: true`、必需的标 `required: true`。
-4. **contracts**：识别对外接口——HTTP 路由文件、CLI flags、导出的公共 API、proto/schema、事件。**尽量给 `snapshot` 命令**（打印当前接口指纹到 stdout，如 `grep -oE '"/api/[^"]*"' src/routes.ts | sort -u`），CLI 会存基线并 diff。给不出自动检查的填 `manual_verify` 说明。
+4. **contracts**：识别对外接口——HTTP 路由文件、CLI flags、导出的公共 API、proto/schema/IDL、事件。**尽量给 `snapshot` 命令**（打印当前接口指纹到 stdout，如 `grep -oE '"/api/[^"]*"' src/routes.ts | sort -u`），CLI 会存基线并 diff。给不出自动检查的填 `manual_verify` 说明（进 GAPS）。两条纪律：(a) **过滤注释/生成物噪音**——配置里被注释掉的示例条目会污染指纹、日后清注释误报 drift，必要时先 `sed 's://.*::'` 剥注释再抓；(b) **命令含引号/正则/管道就下沉到 `.agents/checks/<id>.sh`**（脚本里 `cd` 到仓库根 + `LC_ALL=C` 保跨机字节一致），manifest 里写 `snapshot: bash .agents/checks/<id>.sh`——比把转义地狱硬塞进 YAML 干净，过滤规则也可 review。
 5. **invariants**：从 `CONTRIBUTING` / 现有 `AGENTS.md` / 代码约定提炼"必须始终成立"的规则。**能写成正则的用 `enforcement`**（`forbid_pattern` / `require_pattern` + `path_glob` 限定作用域，glob 是 include-only）；否则标 `manual: true`。
-6. **modules**：主要子系统各写一张模块卡：`role`、`entry`（入口文件，也用于新鲜度绑定）、`upstream` / `downstream`、`must_know`、`pitfalls`（常见坑——最高价值的一栏）。
+6. **modules**：主要子系统各写一张模块卡：`role`、`entry`、`upstream` / `downstream`、`must_know`、`pitfalls`（常见坑——最高价值的一栏）。⚠️ `entry`（以及 knowledge 的 `binds`）必须指到**具体文件**（如 `src/index.ts`），**不能是目录**——它要 hash 文件内容做新鲜度绑定；`routing.read` 用目录则 OK。
 7. **routing**：把常见改动类型（修 bug / 加接口 / 改 UI / 动权限 / 发版…）各写一行：`read`（先读哪些文件）、`entry`、`dont_assume`（别瞎猜什么）、`verify`（最少验证步骤，引用 capability 动词或原始命令）。
 8. **knowledge**：把 agent 从代码推断不出来的东西写进 `.agents/knowledge/`；重要决策建一篇 journal ADR（`knowledge/journal/NNNN-*.md`）。用 `binds` 把知识条目绑定到源文件，源文件变了会触发新鲜度告警。**只沉淀非显然的知识，别记一次性噪音或代码里显而易见的东西。**
 
@@ -66,7 +66,36 @@ harness-kit verify          # 门禁：跑不变量 + 契约 + 漂移，并列
 
 - `harness-kit verify` 退出码 0；`GAPS` 段里每一条都是**真的没法自动查**（打包 / 真网络 / 生产上传 / 人肉不变量），不是偷懒。
 - `AGENTS.md` 在体量预算内（`doctor` 第 6 项会报行数/词数）。
-- 把生成物 + `.agents/` + 契约基线一起提交；告诉用户：**以后改 manifest → `harness-kit sync`，别手改生成物**；把 `harness-kit verify` 挂进 CI / pre-commit 才能真正兑现"跨人跨机一致"。
+- 把生成物 + `.agents/` + 契约基线一起提交；告诉用户：**以后改 manifest → `harness-kit sync`，别手改生成物**。
+- 装上自动化门禁，让防腐烂不靠人自律：
+  ```
+  harness-kit install-hooks --repo .
+  ```
+  pre-commit 自动 sync 并暂存生成物、pre-push 跑 `verify` 拦漂移；团队再把 `harness-kit verify` 放进 CI，才能真正兑现"跨人跨机一致"。
+
+## 5. 日常维护 / 自愈（接入之后，长期靠这个防腐烂）
+
+harness-kit 的持续价值不在首次接入，而在**代码演进时上下文不腐烂**。机制是：门禁发现漂移 → agent 自动修 → 人只 review。**别把维护活丢回给人**——你（agent）来修，人只做最后一次审查。
+
+**触发**：`harness-kit verify` 非零，或 `doctor` 报 drift / 新鲜度告警（装了 pre-push hook 会在 push 时自动拦）。
+
+**自愈流程（你就是那个 agent，按此做）：**
+1. 跑 `harness-kit verify`，逐条读红灯——它已把"哪块过期 / 哪个契约变了 / 该 sync 还是该 accept"写清楚了。
+2. 逐条处理：
+   - **生成物 drift**（"AGENTS.md drifted, run sync"）→ 直接 `harness-kit sync`。
+   - **knowledge 新鲜度告警**（绑定的源文件变了）→ 重新读那个源文件，判断知识是否真过时；过时就改 `.agents/knowledge/*` 或对应 manifest 字段再 sync。**没实质变化就别乱改**。
+   - **契约 drift**（snapshot 变了）→ 看对应代码改动：确属**有意**改接口（有需求 / commit 佐证）才 `harness-kit accept-contract --id <id>`；拿不准是否 breaking 就**别 accept**，标给人。
+   - **invariant 违规** → 按规则修代码；确认该规则已过时才动 manifest。
+3. 全部处理完再 `verify` 到退出码 0。
+4. **产出一份变更清单交给人 review（这是唯一的人工动作）**，至少含：
+   - 改了哪些 manifest 字段 / knowledge 文件，为什么；
+   - accept 了哪些契约、对应什么代码改动、是否 breaking；
+   - 哪些**没动**及原因。
+
+**红线**：
+- 契约 accept 必须有据可依且**必写进给人的清单**——绝不静默 auto-accept 对外接口变更。
+- 拿不准就标 GAP 交人，别用幻觉填。
+- 只修真漂移，别为了凑绿去改无关内容。
 
 ## 反模式（别做）