guarantee-based-coding 0.2.0__py3-none-any.whl

gbc/app/utils/safe_file_writer.py

@@ -0,0 +1,158 @@
+# Copyright 2026 Jesse-x86
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# REQUIREMENTS
+# None, raw python should have all libs required
+# From https://github.com/Jesse-x86/devkit/blob/master/file_operations/safe_file_writer.py
+import logging
+import os
+import shutil
+from pathlib import Path
+
+
+class SafeFileWriter:
+    """
+    一个安全的文件写入器，通过上下文管理器（with语句）提供原子写入和自动备份功能。
+
+    功能特性:
+    1.  **原子性**: 先写入到一个临时文件，只有在with代码块成功执行完毕后，
+        才会用新内容覆盖原文件，有效防止因写入中断导致的文件损坏。
+    2.  **自动备份**: 在覆盖原文件之前，会自动将旧文件备份。
+    3.  **备份管理**: 自动维护指定数量的备份文件（如 .bak1, .bak2 ...），
+        并删除更早的备份。
+    4.  **自动回滚**: 如果with代码块中发生任何异常，临时文件将被删除，
+        原始文件和备份文件将保持不变，实现自动回滚。
+    5.  **灵活写入**: 调用方在with块内可以获得一个标准的文件句柄，可以像操作
+        普通文件一样进行写入（write, writelines, print(file=f)等），
+        完全控制写入的内容和方式。
+
+    使用示例:
+        writer = SafeFileWriter('my_data.json', num_backups=3)
+        try:
+            with writer.open(mode='w', encoding='utf-8') as f:
+                # f 是一个真正的文件句柄，可以自由写入
+                import json
+                json.dump({'key': 'new value'}, f, indent=4)
+                # 假设这里发生错误
+                # raise ValueError("写入过程中发生错误")
+        except Exception as e:
+            print(f"写入失败: {e}")
+
+    # 如果成功，'my_data.json' 会被更新，旧文件变为 'my_data.json.bak1'
+    # 如果失败，'my_data.json' 保持原样，不会产生不完整的文件。
+    """
+
+    def __init__(self, filepath: str | Path, num_backups: int = 0):
+        """
+        初始化SafeFileWriter。
+
+        Args:
+            filepath (str | Path): 目标文件的完整路径。
+            num_backups (int, optional): 需要保留的最大备份数量。默认为 0。
+                                         如果为0，则不创建备份，但仍保证原子写入。
+        """
+        self._mode = None
+        self._open_kwargs = None
+        self.filepath = Path(filepath)
+        self.num_backups = max(0, num_backups)
+        self._temp_path = None
+        self._file_handle = None
+        self._logger = logging.getLogger("SafeFileWriter")
+
+    def _log(self, msg: str):
+        self._logger.debug(msg)
+
+    def _rotate_backups(self):
+        """管理和轮转备份文件。"""
+        if not self.filepath.exists() or self.num_backups == 0:
+            return
+
+        # 1. 删除最旧的备份 (如果存在)
+        oldest_bak = self.filepath.with_suffix(f"{self.filepath.suffix}.bak{self.num_backups}")
+        if oldest_bak.exists():
+            oldest_bak.unlink()
+
+        # 2. 将现有备份序号+1
+        # 从后往前重命名，避免覆盖
+        for i in range(self.num_backups - 1, 0, -1):
+            src_bak = self.filepath.with_suffix(f"{self.filepath.suffix}.bak{i}")
+            dst_bak = self.filepath.with_suffix(f"{self.filepath.suffix}.bak{i + 1}")
+            if src_bak.exists():
+                shutil.move(str(src_bak), str(dst_bak))
+
+        # 3. 将当前文件创建为第一个备份
+        first_bak = self.filepath.with_suffix(f"{self.filepath.suffix}.bak1")
+        shutil.move(str(self.filepath), str(first_bak))
+        self._log(f"备份: {self.filepath.name} -> {first_bak.name}")
+
+    def open(self, mode='w', **kwargs):
+        """
+        以上下文管理器的方式打开文件准备写入。
+
+        Args:
+            mode (str, optional): 文件打开模式，推荐使用 'w' (文本) 或 'wb' (二进制)。
+                                  追加模式 'a' 在此逻辑下意义不大。默认为 'w'。
+            **kwargs: 传递给内建 open() 函数的其他参数, 如 encoding, errors等。
+
+        Returns:
+            一个上下文管理器对象。
+        """
+        self._mode = mode
+        self._open_kwargs = kwargs
+        return self
+
+    def __enter__(self):
+        """上下文管理器的进入方法，准备临时文件。"""
+        # 创建一个唯一的临时文件
+        self._temp_path = self.filepath.with_suffix(f"{self.filepath.suffix}.{os.urandom(6).hex()}.tmp")
+
+        # 打开临时文件用于写入，并将文件句柄返回给 `with ... as f:`
+        self._file_handle = open(self._temp_path, self._mode, **self._open_kwargs)
+        return self._file_handle
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        上下文管理器的退出方法，处理提交或回滚。
+
+        exc_type, exc_val, exc_tb: 如果with块内有异常，这些是异常信息，否则为None。
+        """
+        # 1. 必须确保文件句柄被关闭
+        if self._file_handle and not self._file_handle.closed:
+            self._file_handle.close()
+
+        # 2. 检查with块是否成功执行
+        if exc_type is None:
+            # 成功: 执行备份和替换
+            try:
+                self._log(f"写入成功，准备更新文件: {self.filepath.name}")
+                # a. 轮转备份
+                if self.num_backups > 0:
+                    self._rotate_backups()
+                # b. 将临时文件重命名为目标文件 (原子操作)
+                shutil.move(str(self._temp_path), str(self.filepath))
+                self._log(f"文件已更新: {self.filepath.name}")
+            except Exception as e:
+                self._log(f"错误：在提交文件时发生意外: {e}")
+                # 如果提交阶段也失败了，尝试清理临时文件
+                if self._temp_path.exists():
+                    self._temp_path.unlink()
+                # 让外部知道提交失败了
+                raise
+        else:
+            # 失败: 清理临时文件，不触碰原文件和备份
+            self._log(f"写入失败，正在回滚...")
+            if self._temp_path.exists():
+                self._temp_path.unlink()
+                self._log(f"已删除临时文件: {self._temp_path.name}")
+            # 异常会由Python自动重新抛出，调用方可以捕获它

gbc/assets/editor/index.html

@@ -0,0 +1,299 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>GBC 意图树编辑器</title>
+  <style>
+    :root { --bd:#d0d0d8; --mut:#777; --accent:#3b6ea5; --dir:#2e7d32; }
+    * { box-sizing: border-box; }
+    body { margin:0; font:14px/1.5 system-ui, "Segoe UI", sans-serif; color:#222; }
+    header { display:flex; gap:8px; align-items:center; padding:8px 12px;
+             border-bottom:1px solid var(--bd); background:#fafafc; }
+    header input { flex:1; padding:5px 8px; font:inherit; border:1px solid var(--bd); border-radius:4px; }
+    button { font:inherit; padding:5px 10px; border:1px solid var(--bd); background:#fff;
+             border-radius:4px; cursor:pointer; }
+    button:hover { background:#f0f0f4; }
+    button.primary { background:var(--accent); color:#fff; border-color:var(--accent); }
+    button:disabled { opacity:.5; cursor:default; }
+    .layout { display:flex; height:calc(100vh - 49px); }
+    .tree { width:300px; overflow:auto; border-right:1px solid var(--bd); padding:8px; }
+    .editor { flex:1; overflow:auto; padding:16px 22px; }
+    .trow { display:flex; align-items:center; white-space:nowrap; }
+    .tog { width:16px; text-align:center; cursor:pointer; color:var(--mut); user-select:none; }
+    .tog.leaf { cursor:default; color:#ccc; }
+    .tlabel { cursor:pointer; padding:2px 6px; border-radius:4px; flex:1; }
+    .tlabel:hover { background:#eef; }
+    .tlabel.sel { background:#dde7f3; font-weight:600; }
+    .twrap { margin-left:14px; border-left:1px dotted #ccc; padding-left:6px; }
+    label { display:block; font-weight:600; margin:14px 0 4px; }
+    textarea { width:100%; font:inherit; padding:6px 8px; border:1px solid var(--bd);
+               border-radius:4px; resize:none; overflow:hidden; min-height:2.4em; }
+    .entry { border:1px solid var(--bd); border-radius:6px; padding:10px; margin:8px 0; background:#fcfcfe; }
+    .entry.ghost { opacity:.55; border-style:dashed; background:#f5f5f7; }
+    .entry .row { display:flex; gap:8px; align-items:center; }
+    .entry input.name { font:inherit; padding:4px 6px; border:1px solid var(--bd); border-radius:4px; }
+    .badge { font-size:12px; color:#fff; background:var(--dir); padding:1px 6px; border-radius:10px; }
+    .badge.file { background:#888; }
+    .mut { color:var(--mut); font-size:12px; }
+    .crumb { color:var(--mut); font-size:13px; margin-bottom:4px; }
+    .mirror-note { font-size:12px; color:var(--dir); margin-top:3px; }
+    .msg { margin-left:auto; color:var(--mut); }
+    .empty { padding:24px; color:#777; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script>
+// ---- tiny DOM helper -------------------------------------------------------
+function el(tag, props, ...kids) {
+  const n = document.createElement(tag);
+  for (const k in (props || {})) {
+    if (k === "class") n.className = props[k];
+    else if (k.startsWith("on")) n.addEventListener(k.slice(2), props[k]);
+    else if (k === "value") n.value = props[k];
+    else if (k === "disabled") { if (props[k]) n.disabled = true; }
+    else n.setAttribute(k, props[k]);
+  }
+  for (const c of kids.flat()) {
+    if (c == null || c === false) continue;
+    n.append(c.nodeType ? c : document.createTextNode(String(c)));
+  }
+  return n;
+}
+function sizeTa(t) { t.style.height = "auto"; t.style.height = (t.scrollHeight + 2) + "px"; }
+function ta(props) {
+  return el("textarea", { ...props,
+    oninput: (ev) => { if (props.oninput) props.oninput(ev); sizeTa(ev.target); } });
+}
+
+// ---- state -----------------------------------------------------------------
+const state = { root: "", tree: null, sel: null, msg: "" };
+const collapsed = new Set();
+let _uid = 1;
+
+const HIST_KEY = "gbc_dir_history";
+const getHistory = () => { try { return JSON.parse(localStorage.getItem(HIST_KEY)) || []; } catch { return []; } };
+function pushHistory(p) {
+  if (!p) return;
+  let h = getHistory().filter(x => x !== p);
+  h.unshift(p);
+  localStorage.setItem(HIST_KEY, JSON.stringify(h.slice(0, 12)));
+}
+
+// entry kind derived purely from the name's trailing "/"
+const isDir = (e) => (e.name || "").trim().endsWith("/");
+const folderName = (e) => (e.name || "").trim().replace(/\/+$/, "");
+const bodyText = (e) => isDir(e) ? (e.child ? (e.child.intent || "") : "") : (e.desc || "");
+function childHasContent(e) {
+  const c = e.child;
+  if (!c) return false;
+  if ((c.intent || "").trim() || (c.constraints || "").trim()) return true;
+  return (c.entries || []).some(x => (x.name || "").trim() || bodyText(x).trim() || childHasContent(x));
+}
+// an entry is a "ghost" (grey / deletable) when it carries no content at all
+const isEmpty = (e) => !(e.name || "").trim() && !bodyText(e).trim() && !childHasContent(e);
+
+function assignIds(node) {
+  node._id = _uid++;
+  for (const e of node.entries) if (e.child) assignIds(e.child);
+}
+function findById(node, id, path) {
+  if (node._id === id) return { node, path };
+  for (const e of node.entries) {
+    if (isDir(e) && e.child) {
+      const r = findById(e.child, id, path ? path + "/" + folderName(e) : folderName(e));
+      if (r) return r;
+    }
+  }
+  return null;
+}
+function ensureChild(e) {
+  if (!e.child) e.child = { name: folderName(e), intent: "", constraints: "", entries: [], _id: _uid++ };
+}
+
+// ---- data ops --------------------------------------------------------------
+async function load() {
+  setMsg("加载中…");
+  try {
+    const r = await fetch("/api/tree?root=" + encodeURIComponent(state.root));
+    const t = await r.json();
+    if (!r.ok) throw new Error(t.error || r.statusText);
+    assignIds(t);
+    state.tree = t; state.sel = t._id; collapsed.clear();
+    pushHistory(state.root); setMsg("已加载"); render();
+  } catch (err) { setMsg("加载失败:" + err.message); }
+}
+async function save() {
+  setMsg("保存中…");
+  try {
+    const r = await fetch("/api/tree", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ root: state.root, tree: state.tree }),
+    });
+    const res = await r.json();
+    if (!r.ok) throw new Error(res.error || r.statusText);
+    pushHistory(state.root); setMsg("已写入 " + res.count + " 个 gbc.md"); render();
+  } catch (err) { setMsg("保存失败:" + err.message); }
+}
+function setMsg(m) { state.msg = m; const s = document.querySelector(".msg"); if (s) s.textContent = m; }
+
+// ---- sidebar tree ----------------------------------------------------------
+function treeView(node) {
+  const dirKids = node.entries.filter(e => isDir(e) && e.child);
+  const hasKids = dirKids.length > 0;
+  const open = !collapsed.has(node._id);
+  const toggle = el("span",
+    { class: "tog" + (hasKids ? "" : " leaf"),
+      onclick: () => { if (!hasKids) return; open ? collapsed.add(node._id) : collapsed.delete(node._id); render(); } },
+    hasKids ? (open ? "▾" : "▸") : "•");
+  const label = el("span",
+    { class: "tlabel" + (node._id === state.sel ? " sel" : ""),
+      onclick: () => { state.sel = node._id; render(); } },
+    node.name || "(root)");
+  const kids = (hasKids && open) ? el("div", { class: "twrap" }, dirKids.map(e => treeView(e.child))) : null;
+  return el("div", {}, el("div", { class: "trow" }, toggle, label), kids);
+}
+
+// ---- one entry row: self-managing, keeps focus on type-flip ----------------
+function entryRow(node, e, onGrow) {
+  const root = el("div", { class: "entry" });
+  const bodyWrap = el("div", {});
+  // All row elements are persistent — we NEVER detach nameInput, so typing "/"
+  // (which flips the kind) keeps focus and caret exactly where they are.
+  const badge = el("span", {});
+  const nameInput = el("input", { class: "name", value: e.name || "",
+    placeholder: "名称(结尾带 / = 文件夹)" });
+  const enterBtn = el("button",
+    { onclick: () => { ensureChild(e); state.sel = e.child._id; render(); } }, "进入 →");
+  const delBtn = el("button",
+    { onclick: () => { const i = node.entries.indexOf(e); if (i >= 0) node.entries.splice(i, 1); render(); } },
+    "删除");
+  const rowDiv = el("div", { class: "row" }, badge, nameInput, enterBtn, delBtn);
+
+  const paintGrey = () => root.classList.toggle("ghost", isEmpty(e));
+
+  function paintKind() {
+    const dir = isDir(e);
+    badge.className = "badge" + (dir ? "" : " file");
+    badge.textContent = dir ? "文件夹" : "文件";
+    enterBtn.style.display = dir ? "" : "none";
+
+    bodyWrap.innerHTML = "";                      // bodyWrap holds no focusable name field — safe
+    if (dir) {
+      ensureChild(e);
+      // carry typed text across a file -> folder flip so nothing is lost
+      if (!(e.child.intent || "").trim() && (e.desc || "").trim()) { e.child.intent = e.desc; e.desc = ""; }
+      bodyWrap.append(ta({ rows: 1, value: e.child.intent || "",
+        oninput: ev => { e.child.intent = ev.target.value; paintGrey(); onGrow(); } }));
+      bodyWrap.append(el("div", { class: "mirror-note" },
+        "↔ 同一字段:这就是 " + (folderName(e) || "该文件夹") + "/gbc.md 的意图,改这里=改那里"));
+    } else {
+      if (e.desc == null) e.desc = "";
+      // carry text back on a folder -> file flip
+      if (!e.desc.trim() && e.child && (e.child.intent || "").trim()) { e.desc = e.child.intent; }
+      bodyWrap.append(ta({ rows: 1, value: e.desc,
+        oninput: ev => { e.desc = ev.target.value; paintGrey(); onGrow(); } }));
+    }
+    requestAnimationFrame(() => bodyWrap.querySelectorAll("textarea").forEach(sizeTa));
+  }
+
+  nameInput.addEventListener("input", ev => {
+    const was = isDir(e);
+    e.name = ev.target.value;
+    if (isDir(e) !== was) paintKind();           // in-place: nameInput is untouched, focus stays
+    paintGrey(); onGrow();
+  });
+
+  root.append(rowDiv, bodyWrap);
+  paintKind(); paintGrey();
+  return root;
+}
+
+// ---- entries section: trailing ghost + prune-on-blur -----------------------
+function entriesSection(node) {
+  const container = el("div", {});
+  const ensureGhost = () => {
+    const last = node.entries[node.entries.length - 1];
+    if (!last || !isEmpty(last)) {
+      const g = { name: "", desc: "" };
+      node.entries.push(g);
+      container.append(entryRow(node, g, ensureGhost));
+    }
+  };
+  const rebuild = () => {
+    container.innerHTML = "";
+    node.entries.forEach(e => container.append(entryRow(node, e, ensureGhost)));
+    ensureGhost();
+  };
+  rebuild();
+  container.addEventListener("focusout", () => setTimeout(() => {
+    if (container.contains(document.activeElement)) return;   // still editing in here
+    const kept = node.entries.filter(e => !isEmpty(e));        // drop emptied rows
+    node.entries.length = 0; kept.forEach(e => node.entries.push(e));
+    rebuild();
+  }, 0));
+  return container;
+}
+
+// ---- editor panel ----------------------------------------------------------
+function editor(node, path) {
+  const segs = (path || "").split("/").filter(Boolean);
+  const myName = segs.length ? segs[segs.length - 1] : node.name;
+  return el("div", {},
+    el("div", { class: "crumb" }, path || "(根)"),
+    path ? el("div", { class: "mut" },
+      "↔ 此意图同时显示在父节点的 ## " + myName + "/ 条目里(单一源,双处投影)") : null,
+
+    el("label", {}, "意图 ", el("span", { class: "mut" }, "(# 意图)")),
+    ta({ rows: 1, value: node.intent || "", oninput: ev => { node.intent = ev.target.value; } }),
+
+    el("label", {}, "内部约束 ",
+      el("span", { class: "mut" }, "(# 内部约束 · 可选 · 不冒泡到父节点)")),
+    ta({ rows: 1, value: node.constraints || "", oninput: ev => { node.constraints = ev.target.value; } }),
+
+    el("label", {}, "子项 ",
+      el("span", { class: "mut" }, "(# 文件 段下的 ## · 名称结尾带 / 即文件夹;底部灰条输入即新增,清空失焦即删除)")),
+    entriesSection(node));
+}
+
+// ---- top-level render ------------------------------------------------------
+function render() {
+  const rootEl = document.getElementById("root");
+  rootEl.innerHTML = "";
+
+  const hist = getHistory();
+  rootEl.append(el("header", {},
+    el("input", { value: state.root, placeholder: ".gbc 目录的绝对路径", list: "histlist",
+      oninput: ev => { state.root = ev.target.value; } }),
+    el("datalist", { id: "histlist" }, hist.map(p => el("option", { value: p }))),
+    el("button", { onclick: load }, "加载"),
+    el("button", { class: "primary", disabled: !state.tree, onclick: save }, "保存"),
+    el("span", { class: "msg" }, state.msg)));
+
+  if (!state.tree) {
+    rootEl.append(el("div", { class: "empty" },
+      "输入一个 .gbc 目录路径点「加载」。路径不存在也行 —— 会给你一棵空树,保存时再创建(从零新建)。"));
+    return;
+  }
+  const found = findById(state.tree, state.sel, "");
+  rootEl.append(el("div", { class: "layout" },
+    el("div", { class: "tree" }, treeView(state.tree)),
+    el("div", { class: "editor" }, found ? editor(found.node, found.path) : null)));
+
+  requestAnimationFrame(() => document.querySelectorAll(".editor textarea").forEach(sizeTa));
+}
+
+// ---- init: prefer --root from backend, else most-recent history ------------
+(async function init() {
+  try {
+    const c = await (await fetch("/api/config")).json();
+    if (c.root) { state.root = c.root; render(); await load(); return; }
+  } catch { /* ignore */ }
+  const h = getHistory();
+  if (h.length) state.root = h[0];
+  render();
+})();
+  </script>
+</body>
+</html>

gbc/assets/i18n/catalog/en.json

@@ -0,0 +1,52 @@
+{
+    "_meta.language_name": "English",
+
+    "err.generic": "Error: {msg}",
+    "err.unexpected": "Unexpected error: {kind}: {msg}",
+    "err.illegal_operation": "Illegal operation: {msg}",
+    "err.config": "Config error: {msg}",
+    "err.executor": "Executor error: {msg}",
+    "err.guarantee": "Guarantee error: {msg}",
+    "err.test_failed": "Test failed: {guarantee} on {target}",
+    "err.retire_blocked": "Retire blocked: {msg}",
+    "err.executor_not_found": "Executor config '{name}' not found. Run `gbc executor upsert` to configure it.",
+
+    "exc.illegal_file_path": "Operation intended for '{target}' is illegal",
+    "exc.config_not_found": "Config file '{target}' not found",
+    "exc.config_parse": "Config file '{target}' failed to parse:\n{info}",
+    "exc.project_not_found": "Project '{target}' not found",
+    "exc.meta_not_found": "Meta file '{target}' for '{original}' not found",
+    "exc.guarantee_duplicated": "Guarantee '{gid}' already exists for '{target}'. To update it, use 'update' instead of 'create'",
+    "exc.guarantee_not_found": "Guarantee '{gid}' not found for '{target}'",
+    "exc.guarantee_test_failed": "Guarantee '{gid}' failed for '{target}', failure info:\n{info}",
+    "exc.guarantee_has_dependents": "Guarantee '{gid}' on '{provider}' still has {count} dependent(s): {dependents}. Repair or migrate them first; a guarantee can only be retired once its dependents are empty.",
+    "exc.executor_not_found": "Executor config '{name}' not found",
+    "exc.executor_config_invalid": "Parameters received for executor config '{name}' are invalid",
+    "exc.doc_filename_slash": "A file entry name must not end with '/' (for a subfolder use set-intent <folder>/<sub>): {name}",
+    "exc.doc_name_is_folder": "'{name}' is already a subfolder entry and cannot be changed into a file",
+    "exc.doc_entry_not_found": "Entry not found: {name}",
+
+    "doctor.missing_executor": "This project requires executor '{name}' but it is not configured locally. Run `gbc executor upsert` to add it.",
+    "doctor.executors_ok": "All executors required by this project are configured.",
+
+    "mcp.starting": "Starting GBC MCP server for project: {path}",
+    "editor.starting": "GBC intent editor running at http://{host}:{port}",
+
+    "cli.app.help": "GBC — Guarantee-Based Coding CLI tool",
+    "cli.guarantee.help": "Guarantee CRUD",
+    "cli.dep.help": "Dependency edge registration and reverse lookup",
+    "cli.verify.help": "Run verification",
+    "cli.doctor.help": "Consistency check",
+    "cli.executor.help": "Manage executor configurations",
+    "cli.refactor.help": "Relocate: move files/directories and fix all graph references",
+    "cli.mcp.help": "MCP server (persistent channel for agents)",
+    "cli.editor.help": "Intent editor (persistent web service for humans)",
+    "cli.option.lang.help": "UI/message language zh/en (also via GBC_LANG env var)",
+    "cli.rules.help": "Print the recommended guardrail ruleset to stdout (advisory, not a sandbox)",
+    "cli.setup.help": "Print a localized wiring guide to stdout: how to connect MCP / skills to your agent",
+    "cli.tree.help": "Render the entire .gbc tree as one AI-readable dependency document",
+    "cli.tree.option.detail": "Expand guarantee desc/test/heavy + other artifacts (.pyi) in each .gbc directory",
+    "cli.tree.option.gaps": "Append registration gaps derived from the graph (has json/is depended on but unregistered)",
+    "cli.mcp_up.arg.project_root": "Absolute path to target project root; omit to auto-detect",
+    "cli.doc.help": "Compliant read/write entry for intent docs (gbc.md)"
+}

gbc/assets/i18n/catalog/zh.json

@@ -0,0 +1,52 @@
+{
+    "_meta.language_name": "简体中文",
+
+    "err.generic": "错误：{msg}",
+    "err.unexpected": "意外错误：{kind}：{msg}",
+    "err.illegal_operation": "非法操作：{msg}",
+    "err.config": "配置错误：{msg}",
+    "err.executor": "执行器错误：{msg}",
+    "err.guarantee": "保证错误：{msg}",
+    "err.test_failed": "测试失败：{guarantee}（目标文件 {target}）",
+    "err.retire_blocked": "退休被拦截：{msg}",
+    "err.executor_not_found": "未找到 executor 配置「{name}」。请运行 `gbc executor upsert` 进行配置。",
+
+    "exc.illegal_file_path": "针对「{target}」的操作在意图层面就是非法的",
+    "exc.config_not_found": "配置文件「{target}」未找到",
+    "exc.config_parse": "配置文件「{target}」解析失败：\n{info}",
+    "exc.project_not_found": "项目「{target}」未找到",
+    "exc.meta_not_found": "未找到「{original}」对应的 meta 文件「{target}」",
+    "exc.guarantee_duplicated": "保证「{gid}」已存在于「{target}」。若想更新保证信息，请用 update 而非 create",
+    "exc.guarantee_not_found": "「{target}」上未找到保证「{gid}」",
+    "exc.guarantee_test_failed": "保证「{gid}」在「{target}」上验证失败，失败信息：\n{info}",
+    "exc.guarantee_has_dependents": "「{provider}」上的保证「{gid}」仍有 {count} 个依赖方：{dependents}。请先修复或迁移它们；保证只有在依赖方清空后才能退休。",
+    "exc.executor_not_found": "未找到 executor 配置「{name}」",
+    "exc.executor_config_invalid": "executor 配置「{name}」收到的参数无效",
+    "exc.doc_filename_slash": "文件条目名不应以 / 结尾（子文件夹请用 set-intent <folder>/<sub>）：{name}",
+    "exc.doc_name_is_folder": "「{name}」已是子文件夹条目，不能当文件改",
+    "exc.doc_entry_not_found": "未找到条目：{name}",
+
+    "doctor.missing_executor": "本项目需要 executor「{name}」，但你尚未在本地配置。请运行 `gbc executor upsert` 添加。",
+    "doctor.executors_ok": "本项目所需的 executor 均已配置。",
+
+    "mcp.starting": "正在为项目启动 GBC MCP 服务：{path}",
+    "editor.starting": "GBC 意图编辑器已启动：http://{host}:{port}",
+
+    "cli.app.help": "GBC - Guarantee-Based Coding 命令行工具",
+    "cli.guarantee.help": "保证（Guarantee）增删改查",
+    "cli.dep.help": "依赖边（Dependency）登记与反查",
+    "cli.verify.help": "运行验证",
+    "cli.doctor.help": "一致性体检",
+    "cli.executor.help": "管理执行器配置",
+    "cli.refactor.help": "重定位：移动文件/目录并修全图路径引用",
+    "cli.mcp.help": "MCP 服务（给 agent 的常驻通道）",
+    "cli.editor.help": "意图编辑器（给人的 web 常驻服务）",
+    "cli.option.lang.help": "界面/消息语言 zh/en（也可用环境变量 GBC_LANG）",
+    "cli.rules.help": "打印作者推荐的围栏规则集到 stdout（推荐默认，非强制沙箱）",
+    "cli.setup.help": "打印本地化的接线指南到 stdout：怎么把 MCP / skills 接入你的 agent",
+    "cli.tree.help": "把整棵 .gbc 渲染成一份 AI 可读的依赖树（gbc.md 意图为骨 + json 依赖边）",
+    "cli.tree.option.detail": "展开保证 desc/test/heavy + 每个 .gbc 目录的其它产物(.pyi)",
+    "cli.tree.option.gaps": "末尾附图反推的登记缺口(有 json/被依赖却未登记)",
+    "cli.mcp_up.arg.project_root": "目标项目根的绝对路径；省略则用当前项目判定",
+    "cli.doc.help": "意图文档（gbc.md）的合规读写入口"
+}

gbc/assets/i18n/texts/rules.en.md

@@ -0,0 +1,30 @@
+# GBC Recommended Guardrails (author's suggestions)
+
+> These are **recommended defaults, not an enforced sandbox.** GBC only provides
+> the rule text and guidance; the actual enforcement boundary must be established
+> by your agent framework (e.g. Claude Code's `pre-tool-use` hook).
+> **Installing GBC does NOT make you automatically safe.**
+
+Adopting the following rules in your agent instructions (or enforcing them via your
+framework) will markedly improve the GBC experience:
+
+1. **The top-level agent never edits files inside `.gbc/` directly.** Intent
+   documents are changed only through the gbc-doc entry point; the guarantee graph
+   is touched only through GBC's tools (MCP / CLI). Never hand-edit anything under
+   `.gbc` — its parent/child consistency is a deterministic constraint that stays
+   correct only when maintained through the tools.
+
+2. **Subagents touch neither `.gbc/` files nor any mutating GBC tool / gbc-doc.**
+   A subagent only implements and self-proves via `verify_*`; making commitments
+   (registering guarantees, changing intent) is reserved for the top-level agent.
+
+3. **The top-level agent focuses on planning and aligning intent**, delegating
+   concrete coding to subagents (small changes may be done inline by the top agent).
+
+4. **Enforce the above via your framework.** For example, Claude Code's
+   `pre-tool-use` hook can intercept a subagent's writes to `.gbc/`, or block
+   unauthorized tool calls.
+
+5. **Remember the nature of the boundary.** GBC provides rule text and guidance,
+   not a security guarantee. What actually prevents overreach is your framework
+   configuration — set it up accordingly.

gbc/assets/i18n/texts/rules.zh.md

@@ -0,0 +1,24 @@
+# GBC 推荐围栏规则集（作者建议）
+
+> 这是**推荐默认**，不是强制沙箱。GBC 只提供规则文本与引导；真正的强制边界，
+> 要靠你的 agent 框架（例如 Claude Code 的 `pre-tool-use` hook）来落地。
+> **装了 GBC ≠ 自动安全。**
+
+把下面的规则纳入你的 agent 指令（或用框架机制强制），能显著改善 GBC 的使用体验：
+
+1. **主 agent 不直接编辑 `.gbc/` 内的文件。** 意图文档只经 gbc-doc 入口修改；
+   保证图只经 GBC 的工具（MCP / CLI）操作。绝不手编 `.gbc` 下的任何文件——
+   它的父子一致性是确定性约束，只有经工具维护才不漂移。
+
+2. **subagent 既不碰 `.gbc/` 文件，也不碰任何修改类的 GBC 工具 / gbc-doc。**
+   subagent 只做实现，并用 `verify_*` 自证；登记保证、改意图这类"立约"动作
+   一律留给主 agent。
+
+3. **主 agent 专注规划与对齐意图**，把具体编码任务派给 subagent
+   （小改动可由主 agent 一体完成）。
+
+4. **用框架机制落地上述限制。** 例如 Claude Code 的 `pre-tool-use` hook 可以
+   拦截 subagent 对 `.gbc/` 的写入、或拦截未授权的工具调用。
+
+5. **牢记边界的性质。** GBC 提供的是规则文本与引导，不是安全保证。
+   真正阻止越权的是你的框架配置，请据此设置。