@erzhe/harness-kit 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 > 给 Agent 发一句话，让它帮你把仓库变成 AI 友好的。
 
-harness-kit 把仓库的工程知识（这是什么、怎么跑、什么不能破、改东西看哪）沉淀成一份 `.agents/manifest.yaml`，然后自动生成各家 Agent 的入口文件（`AGENTS.md` / `CLAUDE.md` / Cursor rules），并用门禁保证它们始终一致。
+harness-kit 把仓库的工程知识（这是什么、怎么跑、什么不能破、改东西看哪）沉淀成一份 `.agents/manifest.yaml`，然后自动生成各家 Agent 的入口文件（`AGENTS.md` / `CLAUDE.md`），并用门禁保证它们始终一致。
 
 ---
 
@@ -20,6 +20,7 @@ Onboard 本仓库到 harness-kit：跑 npx -y @erzhe/harness-kit@latest onboard
 2. 扫描你的仓库（读 README、package.json、目录结构…）
 3. 逐块跟你确认着填 `.agents/manifest.yaml`
 4. 跑 `sync` / `doctor` / `verify` 直到全绿
+5. 装上 git 钩子（`install-hooks`）：之后 pre-commit 自动 sync、pre-push verify 拦漂移，维护不用你记命令
 
 全程走 `npx`，不往机器上装任何全局东西；你一发新版，所有人下次执行就用上了。
 
@@ -31,7 +32,6 @@ Onboard 本仓库到 harness-kit：跑 npx -y @erzhe/harness-kit@latest onboard
 你的仓库/
   AGENTS.md                    ← [生成] 跨工具入口，Agent 每次会话必读
   CLAUDE.md                    ← [生成] Claude Code 入口
-  .cursor/rules/               ← [生成] Cursor 规则
   .agents/
     manifest.yaml              ← 你维护的唯一真相源
     knowledge/                 ← Agent 从代码推不出来的知识（领域、约定、决策）
@@ -45,13 +45,29 @@ Onboard 本仓库到 harness-kit：跑 npx -y @erzhe/harness-kit@latest onboard
 
 ---
 
+## 接入之后：自动防腐烂，人只 review
+
+harness-kit 的长期价值不在首次接入，而在**代码演进时上下文不腐烂**——而且这件事不该靠人记命令：
+
+- **装了钩子就无感**：`install-hooks` 之后，pre-commit 自动重生成入口文件、pre-push 跑 `verify`，上下文和代码对不上就红灯拦下。
+- **漂移了让 Agent 自愈**：知识过期 / 接口契约变了，把仓库丢给 Agent 说一句 `onboard`，它会照 skill 自动考古、改 manifest/knowledge、有据才 accept 契约，最后**产出一份变更清单**。
+- **你只做一个动作**：审查那份 diff，批准或打回。生产和更新都交给 Agent，人只 review。
+
+```
+代码演进 → [hook/CI] verify 红灯，指出哪块过期/哪个契约变了
+        → [Agent] 自动修 + 产出变更清单
+        → [你] review：批准 or 打回      ← 唯一的人工动作
+```
+
+---
+
 ## 命令
 
 | 命令 | 作用 |
 | --- | --- |
 | `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 sync` | manifest → 生成 AGENTS.md / CLAUDE.md / routing / modules |
 | `harness-kit doctor` | 体检：完整性 / 路径引用 / 漂移 / 新鲜度 / 体量预算 |
 | `harness-kit verify` | 门禁：跑不变量 + 契约 + 漂移，列出 GAPS，失败非 0 退出 |
 | `harness-kit accept-contract` | 有意变更接口后，记录新的契约指纹为基线 |
@@ -82,7 +98,7 @@ harness-kit 把这些沉淀进 manifest，再确定性地生成与校验。
         │
    harness-kit sync     (确定性生成，勿手改产物)
         ▼
-AGENTS.md / CLAUDE.md / .cursor/rules / .agents/routing.md / .agents/modules.md
+AGENTS.md / CLAUDE.md / .agents/routing.md / .agents/modules.md
         │
    harness-kit verify   (门禁：不变量 + 契约 + 漂移)
         ▼

package/SPEC-v0.md

@@ -29,7 +29,6 @@
 <repo>/
   AGENTS.md                          # [生成] 跨工具入口，<100 行，指路
   CLAUDE.md                          # [生成] 首行 @AGENTS.md
-  .cursor/rules/00-follow-agents.mdc # [生成] 薄适配器
   .agents/                           # canonical 命名空间（唯一手写源）
     manifest.yaml                    # 脊椎（本规范核心，见 §3）
     knowledge/                       # 手写叙述：domain / conventions / journal
@@ -142,7 +141,6 @@ playbooks:
 generate:
   - to: "AGENTS.md"                       render: "identity+capabilities+environment+invariants"
   - to: "CLAUDE.md"                       content: "@AGENTS.md"
-  - to: ".cursor/rules/00-follow-agents.mdc"  template: "adapter"
 ```
 
 **保留动词说明**：`capabilities` 的保留动词全部**可选**——它是一套"共享词汇表"，仓库只声明适用的子集（库通常没有 `run`；前端 `run` 是 dev server 且 `background: true`）。Agent 冷启动时能预期这些词的语义。

package/dist/harness-kit.cjs

@@ -16619,9 +16619,24 @@ function loadManifest(repo) {
 }
 function validateManifest(m) {
   const issues = [];
+  function checkStrArr(arr, prefix) {
+    if (!arr) return;
+    for (let i = 0; i < arr.length; i++) {
+      if (typeof arr[i] !== "string") {
+        issues.push({
+          level: "error",
+          msg: `${prefix}[${i}] \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\uFF08\u5F53\u524D\u662F ${typeof arr[i]}\uFF09`
+        });
+      }
+    }
+  }
   if (!m.spec) issues.push({ level: "error", msg: "\u7F3A\u5C11 spec \u5B57\u6BB5" });
   if (!m.identity?.name) issues.push({ level: "error", msg: "identity.name \u5FC5\u586B" });
   if (!m.identity?.summary) issues.push({ level: "warn", msg: "identity.summary \u5EFA\u8BAE\u586B\u5199" });
+  checkStrArr(m.identity?.scope_in, "identity.scope_in");
+  checkStrArr(m.identity?.scope_out, "identity.scope_out");
+  checkStrArr(m.identity?.upstream, "identity.upstream");
+  checkStrArr(m.identity?.downstream, "identity.downstream");
   for (const [verb, cap] of Object.entries(m.capabilities ?? {})) {
     if (!cap?.run) issues.push({ level: "error", msg: `capabilities.${verb}.run \u5FC5\u586B` });
   }
@@ -16636,11 +16651,23 @@ function validateManifest(m) {
     if (!inv.enforcement && !inv.check && !inv.manual) {
       issues.push({ level: "warn", msg: `invariant ${inv.id} \u65E2\u65E0 enforcement/check \u4E5F\u672A\u6807 manual` });
     }
+    const pfx = `invariant "${inv.id}" \u7684 enforcement`;
+    checkStrArr(inv.enforcement?.forbid_pattern, `${pfx}.forbid_pattern`);
+    checkStrArr(inv.enforcement?.forbid_import, `${pfx}.forbid_import`);
+    checkStrArr(inv.enforcement?.require_pattern, `${pfx}.require_pattern`);
+    checkStrArr(inv.enforcement?.path_glob, `${pfx}.path_glob`);
+  }
+  for (const k of m.knowledge ?? []) {
+    checkStrArr(k.binds, `knowledge "${k.path}" \u7684 binds`);
   }
   const capVerbs = new Set(Object.keys(m.capabilities ?? {}));
   for (const r of m.routing ?? []) {
     if (!r.when) issues.push({ level: "error", msg: "\u5B58\u5728\u7F3A\u5C11 when \u7684 routing \u6761\u76EE" });
+    for (const field of ["read", "entry", "dont_assume", "verify"]) {
+      checkStrArr(r[field], `routing "${r.when}" \u7684 ${field}`);
+    }
     for (const v of r.verify ?? []) {
+      if (typeof v !== "string") continue;
       if (!v.includes(" ") && !capVerbs.has(v))
         issues.push({ level: "warn", msg: `routing "${r.when}" \u7684 verify \u5F15\u7528\u4E86\u672A\u58F0\u660E\u7684 capability: ${v}` });
     }
@@ -16655,16 +16682,24 @@ function validateManifest(m) {
     modSeen.add(mod.name);
     if (!mod.entry?.length)
       issues.push({ level: "warn", msg: `module ${mod.name} \u672A\u58F0\u660E entry\uFF08\u65E0\u6CD5\u505A\u65B0\u9C9C\u5EA6\u7ED1\u5B9A\uFF09` });
+    for (const field of ["entry", "upstream", "downstream", "must_know", "pitfalls"]) {
+      checkStrArr(mod[field], `module "${mod.name}" \u7684 ${field}`);
+    }
   }
   return issues;
 }
 
 // src/render.ts
+function safeStr(v) {
+  if (typeof v === "string") return v;
+  if (v == null) return "";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return JSON.stringify(v);
+}
 function renderTargets(m) {
   const targets = [
     ["AGENTS.md", renderAgentsMd(m)],
-    ["CLAUDE.md", renderClaudeMd()],
-    [".cursor/rules/00-follow-agents.mdc", renderCursorRule()]
+    ["CLAUDE.md", renderClaudeMd()]
   ];
   if (m.routing?.length) targets.push([".agents/routing.md", renderRoutingMd(m)]);
   if (m.modules?.length) targets.push([".agents/modules.md", renderModulesMd(m)]);
@@ -16700,15 +16735,15 @@ function renderAgentsMd(m) {
   L.push("");
   if (id.scope_in?.length || id.scope_out?.length) {
     L.push("## Scope");
-    if (id.scope_in?.length) L.push("", "In scope:", ...id.scope_in.map((s) => `- ${s}`));
+    if (id.scope_in?.length) L.push("", "In scope:", ...id.scope_in.map((s) => `- ${safeStr(s)}`));
     if (id.scope_out?.length)
-      L.push("", "Out of scope (do NOT modify here):", ...id.scope_out.map((s) => `- ${s}`));
+      L.push("", "Out of scope (do NOT modify here):", ...id.scope_out.map((s) => `- ${safeStr(s)}`));
     L.push("");
   }
   if (id.upstream?.length || id.downstream?.length) {
     L.push("## Dependencies");
-    if (id.upstream?.length) L.push("", `Upstream: ${id.upstream.join(", ")}`);
-    if (id.downstream?.length) L.push("", `Downstream: ${id.downstream.join(", ")}`);
+    if (id.upstream?.length) L.push("", `Upstream: ${id.upstream.map(safeStr).join(", ")}`);
+    if (id.downstream?.length) L.push("", `Downstream: ${id.downstream.map(safeStr).join(", ")}`);
     L.push("");
   }
   const caps = Object.entries(m.capabilities ?? {});
@@ -16760,10 +16795,10 @@ function renderRoutingMd(m) {
   L.push("Find the change-type that matches your task and follow that row before editing.", "");
   for (const r of m.routing ?? []) {
     L.push(`## ${r.when}`);
-    if (r.read?.length) L.push(`- Read first: ${r.read.map((s) => `\`${s}\``).join(", ")}`);
-    if (r.entry?.length) L.push(`- Entry points: ${r.entry.map((s) => `\`${s}\``).join(", ")}`);
-    if (r.dont_assume?.length) for (const d of r.dont_assume) L.push(`- Do NOT assume: ${d}`);
-    if (r.verify?.length) L.push(`- Minimum verification: ${r.verify.map((s) => `\`${s}\``).join(", ")}`);
+    if (r.read?.length) L.push(`- Read first: ${r.read.map((s) => `\`${safeStr(s)}\``).join(", ")}`);
+    if (r.entry?.length) L.push(`- Entry points: ${r.entry.map((s) => `\`${safeStr(s)}\``).join(", ")}`);
+    if (r.dont_assume?.length) for (const d of r.dont_assume) L.push(`- Do NOT assume: ${safeStr(d)}`);
+    if (r.verify?.length) L.push(`- Minimum verification: ${r.verify.map((s) => `\`${safeStr(s)}\``).join(", ")}`);
     L.push("");
   }
   return L.join("\n");
@@ -16774,11 +16809,11 @@ function renderModulesMd(m) {
   L.push("# Module map", "");
   for (const mod of m.modules ?? []) {
     L.push(`## ${mod.name} \u2014 ${mod.role}`);
-    if (mod.entry?.length) L.push(`- Entry: ${mod.entry.map((s) => `\`${s}\``).join(", ")}`);
-    if (mod.upstream?.length) L.push(`- Upstream: ${mod.upstream.join(", ")}`);
-    if (mod.downstream?.length) L.push(`- Downstream: ${mod.downstream.join(", ")}`);
-    if (mod.must_know?.length) for (const k of mod.must_know) L.push(`- Must know: ${k}`);
-    if (mod.pitfalls?.length) for (const p of mod.pitfalls) L.push(`- Pitfall: ${p}`);
+    if (mod.entry?.length) L.push(`- Entry: ${mod.entry.map((s) => `\`${safeStr(s)}\``).join(", ")}`);
+    if (mod.upstream?.length) L.push(`- Upstream: ${mod.upstream.map(safeStr).join(", ")}`);
+    if (mod.downstream?.length) L.push(`- Downstream: ${mod.downstream.map(safeStr).join(", ")}`);
+    if (mod.must_know?.length) for (const k of mod.must_know) L.push(`- Must know: ${safeStr(k)}`);
+    if (mod.pitfalls?.length) for (const p of mod.pitfalls) L.push(`- Pitfall: ${safeStr(p)}`);
     L.push("");
   }
   return L.join("\n");
@@ -16789,18 +16824,6 @@ function renderClaudeMd() {
 ${GEN_HEADER()}
 `;
 }
-function renderCursorRule() {
-  return `---
-description: Follow the repo AGENTS.md (generated from .agents/manifest.yaml)
-alwaysApply: true
----
-${GEN_HEADER()}
-
-Read \`AGENTS.md\` at the repo root for project scope, commands, environment,
-contracts, and invariants. It is the single source of truth (generated).
-Do not edit generated files; edit \`.agents/manifest.yaml\` then run \`harness-kit sync\`.
-`;
-}
 
 // src/state.ts
 var import_node_path5 = require("node:path");
@@ -17184,7 +17207,7 @@ 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
+git add AGENTS.md CLAUDE.md .agents >/dev/null 2>&1 || true
 exit 0
 `;
 }
@@ -17286,10 +17309,10 @@ function guard(fn) {
   }
 }
 var program2 = new Command();
-program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.2");
+program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.3");
 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("sync").description("generate tool files (AGENTS.md, CLAUDE.md) 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)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erzhe/harness-kit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": [
@@ -39,14 +39,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "scripts": {
-    "harness": "tsx src/cli.ts",
-    "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": {
     "commander": "^15.0.0",
     "fast-glob": "^3.3.3",
@@ -57,5 +49,12 @@
     "esbuild": "^0.28.1",
     "tsx": "^4.22.5",
     "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "harness": "tsx src/cli.ts",
+    "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"
   }
-}
+}

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

@@ -49,7 +49,7 @@ harness-kit init --repo .
 ## 3. 生成 + 验证到绿
 
 ```
-harness-kit sync            # manifest -> AGENTS.md / CLAUDE.md / .cursor 规则 / routing.md / modules.md
+harness-kit sync            # manifest -> AGENTS.md / CLAUDE.md / routing.md / modules.md
 harness-kit doctor          # 补全度 / 引用路径 / 漂移 / 新鲜度 / 体量预算；按报告修
 harness-kit verify          # 门禁：跑不变量 + 契约 + 漂移，并列出 GAPS
 ```