rulemux 0.1.4 → 0.2.2

package/README.md

@@ -18,9 +18,11 @@ workspace rules directory**. You manage them in one place; they take effect ever
 
 - rulemux **does not own or maintain any rule content**. Your source files stay yours — rulemux
   only copies them. Which agents / workspaces they apply to is declared in your config.
-- **The session hook is only the courier.** It is not used to inject text. Files are really copied
-  into the directory the agent loads natively, so they enjoy static-prefix semantics: they never
-  fade out mid-conversation, and they never accumulate.
+- **The session hook is (almost) only the courier.** Rule *content* is never injected: files are
+  really copied into the directory the agent loads natively, so they enjoy static-prefix semantics
+  (never fade out mid-conversation, never accumulate). The single, deliberate exception is one
+  **transient notice line** the hook emits when it detects that the rules really changed — it asks
+  you to start a new session. See §5.3.
 - Invariants: **no symlinks** (real copies only) and **free add/remove** (delete a source from the
   config and its copy disappears on the next sync).
 
@@ -37,8 +39,7 @@ directory and hook location have been confirmed by a real canary test. Today:
 
 | Agent | Tier | Rules directory | Status |
 |---|---|---|---|
-| **codebuddy** | Tier-1 (real copy) | `.codebuddy/rules/` | ✅ **Verified — installable** |
-| **workbuddy** | Tier-1 (real copy) | `.codebuddy/rules/` (shared with CodeBuddy) | ✅ **Verified — installable** |
+| **codebuddy** | Tier-1 (real copy) | `.codebuddy/rules/` | ✅ **Verified — installable** (`workbuddy` / `codebuddy-cn` are aliases of it: same agent, same dir, same hook) |
 | claude (Claude Code) | Tier-1 | `.claude/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
 | trae (Trae) | Tier-1 | `.trae/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
 | codex | Tier-2 (injection) | none — injects into context | ⚠️ registered, **not verified yet** |
@@ -74,6 +75,18 @@ There is **no auto-update**. Upgrades are manual and handled by your package man
 (`go install …@latest`, Homebrew/Scoop/apt later on). This is a deliberate decision — see
 [design/requirements.md](docs/design/requirements.md) §五.
 
+**An upgrade keeps your hooks current.** A hook command can change between releases (0.2.0 added
+`--hook`), so after `npm i -g rulemux@latest` the npm `postinstall` step rewrites the SessionStart
+hooks rulemux itself had installed — and touches nothing else. For non-npm upgrades, run it yourself:
+
+```bash
+rulemux init --refresh   # rewrite rulemux's OWN hooks only: never installs, never creates files
+```
+
+`rulemux doctor` now reports a hook that is installed but out of date (and how to fix it). If you
+moved this agent's config directory with `CODEBUDDY_CONFIG_DIR`, rulemux follows it — see
+[design/external/agent-rules-dirs.md](docs/design/external/agent-rules-dirs.md) §五.
+
 ---
 
 ## 4. Quick start
@@ -88,7 +101,9 @@ rulemux init --agent codebuddy
 rulemux doctor    # 3. Self-check: binary/PATH, agents, config validity
 rulemux verify    # 4. Canary check: drop a probe and ask the agent to recite its token
 
-# From now on every new session triggers `rulemux sync --agent codebuddy` automatically.
+# From now on every new session triggers `rulemux sync --hook --agent codebuddy` automatically.
+
+rulemux sync --all   # optional: re-align EVERY workspace recorded in the ledger, in one shot
 
 rulemux uninstall --agent codebuddy   # remove rulemux again (--yes skips the confirmation)
 ```
@@ -165,14 +180,24 @@ Things worth knowing:
 ### 5.3 What sync does, and what it never touches
 
 On every sync rulemux computes the set of prefixed files that should exist, then removes any
-`.rulemux__*` file that is not in that set, copies/overwrites the ones that are missing or changed,
+`__rulemux__*` file that is not in that set, copies/overwrites the ones that are missing or changed,
 and skips the rest.
 
-- Destination name: `.rulemux__` + source basename (a short hash is appended on name collisions).
+- Destination name: `__rulemux__` + source basename (a short hash is appended on name collisions).
 - **Your source files are only ever read** — never modified or deleted.
-- **Files without the `.rulemux__` prefix in the rules directory are never touched**, so your own
+- **Files without the `__rulemux__` prefix in the rules directory are never touched**, so your own
   rule files stay safe.
 
+> ⚠️ **Run `rulemux sync` after editing your config or source docs**
+> After you edit `~/.rulemux/config.toml` (adding/removing a `[[source]]`, changing `path`) or any
+> source rule document, run `rulemux sync --agent codebuddy` (omit `--agent` to sync every supported
+> agent).
+> - **If you run sync**: the next new session reads the updated rules.
+> - **If you don't**: CodeBuddy / WorkBuddy still auto-sync on every session start via the SessionStart
+>   hook, but the harness fixes the rule snapshot at the **start of the session** (before the hook runs),
+>   so the current session still sees the old version — the update only takes effect on the **second**
+>   new session.
+
 ---
 
 ## 6. Uninstalling
@@ -184,7 +209,7 @@ rulemux uninstall --agent codebuddy --yes    # skip the confirmation prompt
 ```
 
 It removes rulemux's own hook entry (other tools' hooks in the same file are preserved) and deletes
-the `.rulemux__*` files it previously delivered. Because the hook lives in the user-level config,
+the `__rulemux__*` files it previously delivered. Because the hook lives in the user-level config,
 rulemux also **revisits every workspace recorded in its ledger** (`~/.rulemux/workspaces.json`) and
 cleans those too — otherwise, with the hook gone, that residue could never be removed again. You are
 shown the list of workspaces before anything is deleted.
@@ -195,9 +220,11 @@ shown the list of workspaces before anything is deleted.
 
 | Command | What it does |
 |---|---|
-| `rulemux sync [--agent <id>] [--config <path>] [--workspace <dir>]` | Sync rules (called by each agent's SessionStart hook) |
+| `rulemux sync [--hook] [--agent <id>] [--config <path>] [--workspace <dir>]` | Sync rules. `--hook` = this run comes from an agent's SessionStart hook (only then may it create the rules dir and emit the change notice); omit `--agent` to target every supported agent |
+| `rulemux sync --all [--config <path>]` | Manually re-align every workspace recorded in the ledger (never reads cwd, never creates dirs, prunes ledger entries whose directory is gone). Mutually exclusive with `--hook` / `--agent` / `--workspace` |
 | `rulemux inject --agent <id> [--config <path>]` | Tier-2: print rules to stdout for hook injection |
 | `rulemux init --agent <id[,id...]> [--config <path>] [--workspace <dir>]` | Write a sample config and install the SessionStart hook |
+| `rulemux init --refresh [--agent <id[,id...]>] [--workspace <dir>]` | Refresh **only** the hooks rulemux already installed (npm `postinstall` calls this). Never adds a hook, never creates a file or directory, preserves every other entry and key in the host config |
 | `rulemux doctor [--config <path>] [--workspace <dir>]` | Environment self-check |
 | `rulemux verify --agent <id> [--clean] [--workspace <dir>]` | Canary acceptance test |
 | `rulemux uninstall --agent <id[,id...]> \| --off \| --all [--yes]` | Remove hooks and delivered files |

package/README.zh-CN.md

@@ -16,8 +16,9 @@
 
 - rulemux **不持有、不维护任何规则内容**。源文件完全由你维护，rulemux 只负责复制；
   「适用于哪些 agent / 哪些工作区」在你的配置里声明。
-- **会话钩子只当「投递员」，不用来注入文本**。文件是真正拷进 agent 原生加载的目录，
+- **会话钩子（几乎）只当「投递员」**：规则**正文**从不注入，文件是真正拷进 agent 原生加载的目录，
   因此享有静态前缀语义 —— 不会随对话老化淡出，也不会每轮累积。
+  唯一刻意的例外：当钩子检测到规则**确有变化**时，会注入**一条瞬态提示**，请你新开会话（见 §5.3）。
 - 底线：**不用软链**（一律真实拷贝）、**加删自由**（配置里删掉某源文件，下次同步它的副本即消失）。
 
 > 为什么不直接用钩子注入？注入落在上下文的动态区，压缩时会被摘要掉（淡出），
@@ -32,8 +33,7 @@ rulemux **每个 agent 一套适配器**；只有「规则目录 + 钩子落点
 
 | Agent | 层级 | 规则目录 | 状态 |
 |---|---|---|---|
-| **codebuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/` | ✅ **已验证，可安装** |
-| **workbuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/`（与 CodeBuddy 共用） | ✅ **已验证，可安装** |
+| **codebuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/` | ✅ **已验证，可安装**（`workbuddy` / `codebuddy-cn` 是它的别名：同一 agent、同一目录、同一钩子） |
 | claude（Claude Code） | Tier-1 | `.claude/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
 | trae（Trae） | Tier-1 | `.trae/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
 | codex | Tier-2（注入） | 无 —— 注入上下文 | ⚠️ 已注册，**尚未验证** |
@@ -67,6 +67,18 @@ npm i -g rulemux
 **没有自动更新**。升级手动、交给包管理器（`go install …@latest`，将来 Homebrew / Scoop / apt）。
 这是刻意决策，见 [`docs/design/requirements.md`](docs/design/requirements.md) §五。
 
+**升级会自动把你的钩子刷新到当前格式。** 钩子命令会随版本变化（0.2.0 起加了 `--hook`），所以
+`npm i -g rulemux@latest` 之后，npm 的 `postinstall` 会**只重写 rulemux 自己装过的那条** SessionStart
+钩子 —— 别的条目、别的键一个字节都不动。非 npm 方式升级的，自己跑一条即可：
+
+```bash
+rulemux init --refresh   # 只刷新「我们自己装过的」钩子：不新增、不创建任何文件或目录
+```
+
+`rulemux doctor` 现在能报出「已安装但格式过期」，并给出上面这条修复命令。若你用
+`CODEBUDDY_CONFIG_DIR` 把该 agent 的配置目录挪走过，rulemux 会跟随 —— 见
+[`docs/design/external/agent-rules-dirs.md`](docs/design/external/agent-rules-dirs.md) §五。
+
 ---
 
 ## 4. 快速开始
@@ -81,7 +93,9 @@ rulemux init --agent codebuddy
 rulemux doctor    # 3. 自检：二进制/PATH、各 agent 状态、配置合法性
 rulemux verify    # 4. canary 验收：投放探针，开新会话让 agent 念出暗号
 
-# 此后每次开新会话，都会自动触发 rulemux sync --agent codebuddy
+# 此后每次开新会话，都会自动触发 rulemux sync --hook --agent codebuddy
+
+rulemux sync --all   # 可选：一条命令把账本里记录过的所有工作区重新对齐
 
 rulemux uninstall --agent codebuddy   # 卸载（--yes 跳过确认）
 ```
@@ -154,12 +168,22 @@ workspace        = ["/path/to/standalone"] # 也可与 workspace_groups 同时
 
 ### 5.3 同步做了什么，以及绝不碰什么
 
-每次同步：算出「应该存在的带前缀文件集合」，目标目录里不在这个集合中的 `.rulemux__*` 一律删除（删残留），
+每次同步：算出「应该存在的带前缀文件集合」，目标目录里不在这个集合中的 `__rulemux__*` 一律删除（删残留），
 缺失或内容不一致的复制/覆盖，其余跳过。
 
-- 目标文件名：`.rulemux__` + 源 basename（同名冲突时追加短 hash）。
+- 目标文件名：`__rulemux__` + 源 basename（同名冲突时追加短 hash）。
 - **源文件只被读取** —— 绝不修改、绝不删除。
-- **规则目录里不带 `.rulemux__` 前缀的文件绝不触碰**，你自己的规则文件始终安全。
+- **规则目录里不带 `__rulemux__` 前缀的文件绝不触碰**，你自己的规则文件始终安全。
+
+> ⚠️ **规则改了，要等下一个会话生效 —— 而且 agent 会主动告诉你**
+> SessionStart 钩子每次会话都会同步、并把文件真正拷到磁盘。但 harness 在会话**开始瞬间**就固定了规则快照
+> （早于钩子执行），所以本次会话读到的仍是旧版，改动要**下一个**会话才会被加载。
+> 钩子检测到规则**确有变化**（新增 / 修改 / 删除）时，会注入**一句话**请模型转告你「请新开会话」；
+> **没有变化时它一个字节都不输出**。
+>
+> 想一次性把所有工作区都对齐？`rulemux sync --all` 会遍历账本（`~/.rulemux/workspaces.json`）里记录过的
+> 每个工作区重新同步。它**绝不创建**规则目录（只有该 agent 自己的会话钩子才会创建），并顺手清掉账本里
+> 「目录已经不存在」的条目。
 
 ---
 
@@ -171,7 +195,7 @@ rulemux uninstall --off                      # 全部 agent（--all 等价）
 rulemux uninstall --agent codebuddy --yes    # 跳过交互确认
 ```
 
-它会移除 rulemux 自己的钩子条目（同一文件里其它工具的钩子会保留），并删掉此前投递的 `.rulemux__*` 文件。
+它会移除 rulemux 自己的钩子条目（同一文件里其它工具的钩子会保留），并删掉此前投递的 `__rulemux__*` 文件。
 由于钩子在 user 级配置里，rulemux 还会**按账本（~/.rulemux/workspaces.json）回访所有记录过的工作区**
 一并清理 —— 否则钩子一去，那些残留就再没机会被删掉了。删除前会把要回访的工作区列表给你确认。
 
@@ -181,9 +205,11 @@ rulemux uninstall --agent codebuddy --yes    # 跳过交互确认
 
 | 命令 | 作用 |
 |---|---|
-| `rulemux sync [--agent <id>] [--config <path>] [--workspace <dir>]` | 同步规则（由各 agent 的 SessionStart 钩子调用） |
+| `rulemux sync [--hook] [--agent <id>] [--config <path>] [--workspace <dir>]` | 同步规则。`--hook` = 本次由某 agent 的 SessionStart 钩子调起（**只有此时**才允许创建规则目录、才可能输出变化提示）；省略 `--agent` 则针对全部已支持 agent |
+| `rulemux sync --all [--config <path>]` | 手动把账本里记录过的所有工作区重新对齐（不读 cwd、绝不创建目录、顺手 GC 掉目录已不在的条目）。与 `--hook` / `--agent` / `--workspace` 互斥 |
 | `rulemux inject --agent <id> [--config <path>]` | Tier-2：把规则输出到 stdout 供钩子注入 |
 | `rulemux init --agent <id[,id...]> [--config <path>] [--workspace <dir>]` | 生成示例配置并安装 SessionStart 钩子 |
+| `rulemux init --refresh [--agent <id[,id...]>] [--workspace <dir>]` | **只刷新** rulemux 自己装过的钩子（npm `postinstall` 调用的就是它）：不新增、不创建任何文件或目录、文件里其它条目与其它键一律原样保留 |
 | `rulemux doctor [--config <path>] [--workspace <dir>]` | 环境自检 |
 | `rulemux verify --agent <id> [--clean] [--workspace <dir>]` | canary 验收 |
 | `rulemux uninstall --agent <id[,id...]> \| --off \| --all [--yes]` | 移除钩子与已投递文件 |

package/bin/postinstall.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+
+// npm postinstall: bring rulemux's own SessionStart hooks up to date after a
+// global install/upgrade.
+//
+// Why: a hook command can change between releases (0.2.0 added `--hook`). Users
+// who upgraded but never re-ran `init` would silently keep the old behaviour,
+// so the upgrade itself refreshes what it previously wrote.
+//
+// Deliberate limits — this script must never surprise anyone:
+//   - global installs only: a project-local `npm i rulemux` must not touch the
+//     user's host config;
+//   - skipped under CI, sudo and --ignore-scripts: $HOME would point at the
+//     wrong user, or the run is not a real user's machine;
+//   - it never installs anything new: only hooks rulemux itself already wrote;
+//   - it never fails the install: every error path exits 0, silently.
+//
+// Non-npm installs (go install, a binary from GitHub Releases) have no
+// postinstall. Those users run `rulemux init --refresh` themselves, and
+// `rulemux doctor` reports hooks that are installed but outdated.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function platformKey() {
+  const plat = process.platform === "win32" ? "windows" : process.platform;
+  let arch = process.arch;
+  if (arch === "x64") arch = "amd64";
+  else if (arch === "ia32") arch = "386";
+  return `${plat}-${arch}`;
+}
+
+// Same resolution order as bin/rulemux.js: a bundled binary first, then a
+// `rulemux` already on PATH.
+function resolveBinary() {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const key = platformKey();
+  const candidates = [
+    path.join(__dirname, "..", "dist", `rulemux-${key}${ext}`),
+    path.join(__dirname, "..", "dist", `rulemux-${process.platform}-${process.arch}${ext}`),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  const which = process.platform === "win32" ? "where" : "which";
+  const r = spawnSync(which, ["rulemux"], { stdio: "ignore" });
+  return r.status === 0 ? "rulemux" : null;
+}
+
+function shouldRun() {
+  if (process.env.npm_config_global !== "true") return false;
+  if (process.env.npm_config_ignore_scripts === "true") return false;
+  if (process.env.CI) return false;
+  if (process.env.SUDO_USER) return false;
+  return true;
+}
+
+function main() {
+  if (!shouldRun()) return;
+
+  const bin = resolveBinary();
+  if (!bin) return;
+
+  const r = spawnSync(bin, ["init", "--refresh"], { encoding: "utf8" });
+  if (r.error || r.status !== 0 || !r.stdout) return;
+
+  // Stay quiet unless something actually changed: "refreshed:" marks a rewrite.
+  const changed = r.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.includes("refreshed:"));
+  if (changed.length === 0) return;
+
+  process.stdout.write(
+    "rulemux: upgraded the SessionStart hook(s) rulemux had already installed\n" +
+      changed.map((line) => "  " + line).join("\n") +
+      "\n"
+  );
+}
+
+try {
+  main();
+} catch (_) {
+  // Never let a hook refresh break `npm install`.
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulemux",
-  "version": "0.1.4",
+  "version": "0.2.2",
   "description": "One set of rules, delivered to every AI coding agent: copies the rule files you declare into each agent's native workspace rules directory, with the same effect and token cost as writing AGENTS.md by hand.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
   ],
   "scripts": {
     "build:dist": "bash scripts/build-dist.sh",
+    "postinstall": "node bin/postinstall.js",
     "prepublishOnly": "npm run build:dist"
   },
   "engines": {