agents-gitflow-guard 0.0.11 → 0.0.13

package/README.md

@@ -42,10 +42,11 @@ You define your own branches —
 # installs the latest release
 dsh plugin --profile web add agents-gitflow-guard
 # ...or pin an exact known-good version (recommended; also bypasses stale registry caches)
-dsh plugin --profile web add agents-gitflow-guard@0.0.9
+dsh plugin --profile web add agents-gitflow-guard@0.0.13
 ```
 
 > **Version gotcha**: a bare `add` resolves whatever `latest` is at install time — on machines behind a stale npm/pnpm registry cache or mirror it may install an old version. If the installed version looks wrong, pin it explicitly. The peer-dependency *warning* pnpm may print is expected: DSH supplies `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` through its shared profile module fallback at startup (the plugin works normally).
+
 **Step 2 — configure**, create `gitflow-guard.config.json` in your **project root**:
 
 ```jsonc
@@ -256,7 +257,7 @@ archive (optional; you archive after release)
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // optional
     "archive":     ["main"]                                      // optional
   },
-  "locale": "en",                      // optional: message language ('en' default, or 'zh')
+  "locale": "en",                      // optional: message language — any registered locale ('en'/'zh' built-in); unknown values warn in status and fall back to English
   "strict": false,                     // optional: fail-closed — invalid config / internal errors block instead of warn-and-allow
   "ci": { "enabled": true }            // optional: gh pr checks logged as reference
 }
@@ -265,8 +266,18 @@ archive (optional; you archive after release)
 - Roles accept either an **array** (shorthand) or an **object** `{ branches, update?, mergeBy? }`.
 - `update`: `pr` (default) = updates only via PR/MR; `flexible` = allow direct/local merges (small teams).
 - `mergeBy` (production): `user` (default) = only you click merge; `anyone` = allow PR merge through.
-- Each branch entry is an exact name or a regex (auto-detected).
-- **Language**: messages are English by default; add `"locale": "zh"` for Chinese.
+- Each branch entry is an exact name or a regex (auto-detected). **Regex safety**: branch patterns are authored by you and compiled as-is — avoid catastrophic-backtracking constructs (e.g. nested quantifiers like `(\w+)+`) in `featurePattern` and branch entries.
+- **Language**: messages are English by default; add `"locale": "zh"` for Chinese, or pass `--locale <en|zh>` to any `gitflow-guard` subcommand (priority: CLI flag > project config > English). All user-facing text follows the locale — including CLI framework messages such as `--help`, unknown-command notices, and the empty-audit line.
+- **Custom locales**: downstream packages can add a language at runtime — `import { registerLocale } from 'agents-gitflow-guard'`, call `registerLocale('fr', frDict)` with a dictionary covering exactly the same keys as built-in English (validated on registration), then set `"locale": "fr"` in the project config to activate it.
+
+  ```js
+  import { registerLocale, MESSAGE_KEYS } from 'agents-gitflow-guard'
+  // MESSAGE_KEYS lists every key a dictionary must define (same set as built-in English);
+  // registration throws if a key is missing or extra.
+  const fr = { /* one entry per MESSAGE_KEYS, e.g. */ 'deny.header': ({ why }) => `[gitflow-guard] bloqué : ${why}` }
+  registerLocale('fr', fr)
+  ```
+- **Unknown locales**: an unregistered `"locale"` value falls back to English during interception (by design — hooks never stall on wording), so a typo is easy to miss; the one-line warning shows up in `gitflow-guard status`.
 - **Validation**: `integration` is required; overlapping role entries are rejected; invalid regex is rejected. **Any error disables the plugin for that project** (reported) rather than applying a half-guessed setup.
 - **Strict mode**: by default a broken config warns on stderr once and lets the command pass (fail-open, so a typo can't wedge your tooling). `"strict": true` flips config errors and internal errors to **block** (fail-closed) — for high-risk repos. A missing file or explicit `enabled: false` stays silent either way.
 
@@ -296,12 +307,12 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 ---
 ## Installation in detail
 
-**Prerequisite**: a working [DSH](https://github.com/deepseek-ai/deepseek-harness) installation.
+**Prerequisite**: a working [DSH](https://github.com/deepseek-ai/deepseek-harness) installation and **Node.js ≥ 22** on your `PATH` (matches the package `engines` floor and the lowest CI matrix tier — standalone hook users bypass npm but still need the runtime).
 
 **From the npm registry** — the standard path, already covered in [Quick Start](#quick-start--30-seconds-to-a-guarded-repo):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.9    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.13    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -401,7 +412,7 @@ What remains **locally non-defensible**: direct forge-API calls (`gh api repos/
 
 ### Why can't the agent just merge into production/archive itself?
 
-Because the gate classifies those as **user-only** actions. An agent may create the PR/MR, but the plugin denies the *merge* for production and the *PR creation* (and merge) for archive. The only path is for **you** to click merge — there is no permit, token, or chat message an agent could use to confer that power on itself.
+Because the gate classifies those as **user-only** actions. The plugin denies the *merge* for production and for archive — creating a PR/MR stays allowed, so an agent can still draft a `develop` → `main` archive PR for you. The merge itself, however, has exactly one path: **you** clicking it — there is no permit, token, or chat message an agent could use to confer that power on itself.
 
 ---
 
@@ -421,7 +432,7 @@ The blocks are reserved for: (1) direct writes to protected role branches, and (
 
 ### What if my config has a mistake?
 
-The plugin prefers failing closed: any validation error disables the guard for that project and reports the errors, so a half-guessed setup never applies by accident.
+A half-guessed setup is never applied by accident: any validation error disables the guard for that project and reports the errors.
 
 Common mistakes: missing `integration` (required), overlapping a branch across two roles (rejected explicitly), and a `featurePattern` that doesn't compile (rejected as invalid regex). The failure is loud and the file is one JSON object, so the fix is usually a thirty-second correction.
 
@@ -480,15 +491,15 @@ The plugin is free and open source (MIT). If it saves you and your team from a s
 
 ```bash
 npm install
-npm test          # unit tests: classify / gate / config / cli / repo / platform
+npm test          # unit tests: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit
 npm run typecheck     # tsc --noEmit, 0 errors
 npm run build         # tsdown → lib/ (CLI and plugin share the build)
-npm run verify:matrix # continuous cross-agent regression: DSH logic + Claude Code / Codex / antigravity hook wiring
+npm run verify:matrix # continuous cross-agent regression: DSH logic + zh-locale regression + Claude Code / Codex / OpenCode / Antigravity hook wiring
 ```
 
 **Rule**: any logic change must pass a 0-error build + all green tests + a green `verify:matrix` before done.
 
-**Adding a new agent client** (e.g. Gemini / OpenCode / Cursor): all of these must change in one commit — `src/platform.ts` (+tests, `HookPlatform` union), a repo hook config beside `.claude/settings.json` / `.codex/hooks.json`, `.agents/hooks/references/<tool>.md`, `scripts/verify-matrix.mjs`, the README hook section and the top tagline, `package.json` description/keywords, and `CHANGELOG`. Done only when `npm run verify:matrix` is green. (Same checklist in [AGENTS.md](AGENTS.md) §8.)
+**Adding a new agent client** (e.g. Cursor / Windsurf): all of these must change in one commit — `src/platform.ts` (+tests, `HookPlatform` union), a repo hook config beside `.claude/settings.json` / `.codex/hooks.json`, `.agents/hooks/references/<tool>.md`, `scripts/verify-matrix.mjs`, the README hook section and the top tagline, `package.json` description/keywords, and `CHANGELOG`. Done only when `npm run verify:matrix` is green. (Same checklist in [AGENTS.md](AGENTS.md) §8.)
 
 ---
 
@@ -496,4 +507,4 @@ npm run verify:matrix # continuous cross-agent regression: DSH logic + Claude Co
 
 [MIT](LICENSE) © FeatureAgents
 
-Design specification (Chinese, decision record): [docs/design.md](docs/design.md).
+Historical v0 design decisions (Chinese; superseded by the role-driven model shipped in 0.0.2 — current behavior is documented in this README): [docs/design.md](docs/design.md).

package/README.zh.md

@@ -41,10 +41,11 @@
 # 安装最新版
 dsh plugin --profile web add agents-gitflow-guard
 # ...或锁定已知良好版本(推荐; 同时绕开 registry 陈旧缓存)
-dsh plugin --profile web add agents-gitflow-guard@0.0.9
+dsh plugin --profile web add agents-gitflow-guard@0.0.13
 ```
 
 > **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
+
 **第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
 
 ```jsonc
@@ -253,7 +254,7 @@ archive(可选, 发布后你亲手归档)
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // 可选
     "archive":     ["main"]                                      // 可选
   },
-  "locale": "en",                      // 可选: 文案语言('en' 默认, 或 'zh')
+  "locale": "en",                      // 可选: 文案语言——任意已注册 locale('en'/'zh' 内置); 未注册值在 status 告警并回退英文
   "strict": false,                     // 可选: fail-closed —— 配置异常/内部错误改为拦截, 而非告警放行
   "ci": { "enabled": true }            // 可选: gh pr checks 作参考日志
 }
@@ -262,8 +263,17 @@ archive(可选, 发布后你亲手归档)
 - 每个角色既可用**数组**(简写),也可用**对象** `{ branches, update?, mergeBy? }`。
 - `update`:`pr`(默认)= 只能 PR/MR 合入;`flexible` = 允许直推/本地合入(小团队)。
 - `mergeBy`(生产):`user`(默认)= 只能你点合并;`anyone` = 放行 PR 合并。
-- 每条分支条目是精确名或正则(自动识别)。
-- **文案语言**:默认英文;加 `"locale": "zh"` 切中文。
+- 每条分支条目是精确名或正则(自动识别)。**正则安全**:分支正则由项目作者提供并按原样编译——`featurePattern` 与分支条目请避免灾难性回溯写法(如 `(\w+)+` 这类嵌套量词)。
+- **文案语言**:默认英文;加 `"locale": "zh"` 切中文,或给任意 `gitflow-guard` 子命令传 `--locale <en|zh>`(优先级:CLI 旗标 > 项目配置 > 英文)。全部用户可见文案都跟随 locale——包括 `--help`、未知子命令提示、审计为空的提示等 CLI 框架文案。
+- **自定义语言**:下游包可在运行时追加语言——`import { registerLocale } from 'agents-gitflow-guard'`,调用 `registerLocale('fr', frDict)` 注册一份与内置英文键完全一致的字典(注册时校验),再在项目配置写 `"locale": "fr"` 即生效。
+
+  ```js
+  import { registerLocale, MESSAGE_KEYS } from 'agents-gitflow-guard'
+  // MESSAGE_KEYS 列出字典必须覆盖的全部键(与内置英文同一键集);缺键/多键注册即抛错。
+  const fr = { /* 每个 MESSAGE_KEYS 一条, 如 */ 'deny.header': ({ why }) => `[gitflow-guard] bloqué : ${why}` }
+  registerLocale('fr', fr)
+  ```
+- **未注册语言**:拦截路径对未注册的 `"locale"` 静默回退英文(设计如此——hook 不因文案缺失卡死),笔误因此容易被忽略;一行告警在 `gitflow-guard status` 中可见。
 - **校验**:`integration` 必填;角色条目重叠会被拒;非法正则会报错。**任何错误都会让该项目的插件禁用并上报**(而不是用半吊子配置)。
 - **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。文件不存在或显式 `enabled: false` 两种模式下都保持静默。
 
@@ -277,7 +287,7 @@ archive(可选, 发布后你亲手归档)
 | 直推 / 强推 / 删除 integration / preview / production / archive | 🚫 拦(integration/preview 配 `flexible` 时直推放行) |
 | PR/MR: feature → integration / preview | ✅ 放行 |
 | PR/MR: feature → production | ✅ 可创建;**合并被拦**(你在 UI 合并) |
-| 指向 archive 的 PR/MR | 🚫 拦 |
+| 指向 archive 的 PR/MR | ✅ 可创建;🚫 合并被拦(你在 UI 合并) |
 | 在 integration / preview 上 `git merge feature/x`(本地) | 🚫 拦(须 PR/MR);`update: flexible` 则放行 |
 | 串联命令(`checkout develop && merge feature/x`) | 🚫 拦——逐段模拟分支切换,无法绕序 |
 
@@ -293,12 +303,12 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 ---
 ## 安装详解
 
-**前置**:一个可用的 [DSH](https://github.com/deepseek-ai/deepseek-harness) 安装。
+**前置**:一个可用的 [DSH](https://github.com/deepseek-ai/deepseek-harness) 安装,且 `PATH` 上有 **Node.js ≥ 22**(与包 `engines` 及 CI 矩阵最低档一致——独立 hook 用户不经 npm 安装,同样需要运行时)。
 
 **从 npm registry**——标准路径,已在[快速开始](#快速开始30-秒用上)覆盖:
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.9    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.13    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -398,7 +408,7 @@ hooks:
 
 ### 为什么 agent 不能自己合并进生产/归档?
 
-因为门禁把那些动作判定为**仅用户**。agent 可以创建 PR/MR,但对生产的*合并*、对归档的*建 PR 与合并*插件一律拒绝。唯一路径是**你**点合并——不存在 agent 能用来给自己授权的特许、令牌或聊天消息。
+因为门禁把那些动作判定为**仅用户**。插件对生产的*合并*、归档的*合并*一律拦截——*建 PR/MR 允许*,agent 仍可替你起草 develop→main 归档 PR。但合并本身只有一条路径:**你**亲手点合并——不存在 agent 能用来给自己授权的特许、令牌或聊天消息。
 
 ---
 
@@ -418,7 +428,7 @@ hooks:
 
 ### 配置写错了会怎样?
 
-插件偏好 fail-closed:任何校验错误都会让该项目的守卫禁用并上报错误,半吊子配置绝不会意外生效。
+半吊子配置绝不会意外生效:任何校验错误都会让该项目的守卫禁用并上报错误。
 
 常见错误:`integration` 缺失(必填)、同一个分支被配到两个角色里(显式拒绝)、`featurePattern` 写不成合法正则(报错)。失败提示很明确,文件又是一个 JSON 对象,通常三十秒改好。
 
@@ -446,7 +456,7 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 | **integration** | 集成分支,唯一必填角色(`branches.integration`);feature 经 PR/MR 合入;受保护 |
 | **preview** | 可选环境终点分支(`branches.preview`,数组);只走 PR/MR 更新 |
 | **production** | 可选生产分支(`branches.production`,数组);PR/MR + 合并仅限用户 |
-| **archive** | `branches.archive`(数组) | 可选 | 允许 agent 创建指向它的 PR/MR; 合并仍限用户亲手 |
+| **archive** | 可选的发布后归档分支(`branches.archive`,数组);允许 agent 创建指向它的 PR/MR,合并仍限用户亲手 |
 | **feature 分支** | 你的工作分支,由 `featurePattern` 识别;自由区 |
 | **门禁矩阵** | 把每条被分类的命令映射为放行/拦截的判定表 |
 | **pre-execute** | 工具管线中拦截发生的钩子——在命令运行之前 |
@@ -477,12 +487,15 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 
 ```bash
 npm install
-npm test          # 单测: classify / gate / config / cli / repo / platform
+npm test          # 单测: classify / gate / config / cli / repo / platform / i18n / index / accuracy-audit
 npm run typecheck     # tsc --noEmit, 0 Error
 npm run build         # tsdown → lib/(CLI 与插件共用)
+npm run verify:matrix # 连续复测矩阵: DSH 逻辑 + zh 文案回归 + Claude Code / Codex / OpenCode / Antigravity hook 编码
 ```
 
-**铁律**:任何逻辑改动必须 0 Error 构建 + 单测全绿后才算完成。
+**铁律**:任何逻辑改动必须 0 Error 构建 + 单测全绿 + 连续复测矩阵(`verify:matrix`)全绿后才算完成。
+
+**接入新的 agent 客户端**(如 Cursor / Windsurf):以下各项必须在同一个 commit 内完成——`src/platform.ts`(含测试与 `HookPlatform` 联合类型)、`.claude/settings.json` / `.codex/hooks.json` 旁新增一份仓库级 hook 配置、`.agents/hooks/references/<tool>.md`、`scripts/verify-matrix.mjs`、README 双语 hook 段与开头宣传语、`package.json` 的 description/keywords,以及 `CHANGELOG`。`npm run verify:matrix` 全绿才算完成。(同一清单见 [AGENTS.md](AGENTS.md) §8;DSH 为进程内插件不走 stdin-hook 清单,见该节例外说明。)
 
 ---
 
@@ -490,4 +503,4 @@ npm run build         # tsdown → lib/(CLI 与插件共用)
 
 [MIT](LICENSE) © FeatureAgents
 
-设计规格(中文,决策记录):[docs/design.md](docs/design.md)。
+v0 历史设计决策(中文;已被 0.0.2 角色驱动模型取代——现行行为以本 README 为准):[docs/design.md](docs/design.md)。

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { c as findRepoRoot, d as resolveLocale, f as loadConfig, i as formatDeny, l as gitRunner, m as classify, o as stateDir, p as roleMatches, r as evaluateCommand, s as currentBranch, u as makeT } from "./src-DTg5WMog.mjs";
+import { c as findRepoRoot, d as roleMatches, g as classify, h as resolveLocale, i as formatDeny, l as gitRunner, o as stateDir, p as makeT, r as evaluateCommand, s as currentBranch, u as loadConfig } from "./src-BHyQJ6hX.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts
@@ -94,31 +94,45 @@ function parseFlags(argv) {
 		else if (a === "--lines") flags.lines = Number(next());
 		else if (a === "--platform") flags.platform = next();
 		else if (a === "--command") flags.command = next();
+		else if (a === "--locale") flags.locale = next();
 		else if (a.startsWith("--repo=")) flags.repo = a.slice(7);
 		else if (a.startsWith("--lines=")) flags.lines = Number(a.slice(8));
 		else if (a.startsWith("--platform=")) flags.platform = a.slice(11);
 		else if (a.startsWith("--command=")) flags.command = a.slice(10);
+		else if (a.startsWith("--locale=")) flags.locale = a.slice(9);
 	}
 	return flags;
 }
-async function resolveRepo(flags) {
+async function resolveRepo(flags, runner) {
 	if (flags.repo) return flags.repo;
-	return await findRepoRoot(gitRunner, process.cwd());
+	return await findRepoRoot(runner, process.cwd());
+}
+/** CLI 文案 locale 解析(P2-1): --locale 旗标 > 项目 config.locale > en; 白名单外一律 en */
+function cliLocale(flags, configLocale) {
+	return resolveLocale(flags.locale ?? configLocale);
+}
+/** 无 config 在手时的 locale 解析(help / unknownCommand 等框架路径): 旗标优先, 否则定位仓库读配置 */
+async function resolveFrameworkLocale(flags, runner) {
+	if (flags.locale != null) return resolveLocale(flags.locale);
+	const repoRoot = await resolveRepo(flags, runner);
+	if (!repoRoot) return "en";
+	const { config } = await loadConfig(repoRoot);
+	return resolveLocale(config?.locale);
 }
 async function main(argv, opts = {}) {
 	const runner = opts.runner ?? gitRunner;
-	const usage = makeT("en")("usage.text");
 	const [cmd, ...rest] = argv;
+	const flags = parseFlags(rest);
 	if (cmd === "--help" || cmd === "help" || cmd === void 0) {
-		console.log(usage);
+		console.log(makeT(await resolveFrameworkLocale(flags, runner))("usage.text"));
 		return 0;
 	}
-	const flags = parseFlags(rest);
 	try {
 		if (cmd === "status") return await status(flags, runner);
 		if (cmd === "audit") return await audit(flags);
 		if (cmd === "check") return await check(flags);
-		console.error(`${makeT("en")("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${usage}`);
+		const t = makeT(await resolveFrameworkLocale(flags, runner));
+		console.error(`${t("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${t("usage.text")}`);
 		return 1;
 	} catch (e) {
 		console.error(`[gitflow-guard] ${e.message}`);
@@ -126,20 +140,22 @@ async function main(argv, opts = {}) {
 	}
 }
 async function status(flags, runner) {
-	const repoRoot = await resolveRepo(flags);
+	const repoRoot = await resolveRepo(flags, runner);
 	if (!repoRoot) {
-		console.error(makeT("en")("cli.cannotLocate"));
+		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
 		return 1;
 	}
-	const { config, errors } = await loadConfig(repoRoot);
+	const { config, errors, warnings } = await loadConfig(repoRoot);
 	const enabled = config?.enabled === true;
-	const t = makeT(resolveLocale(config?.locale));
+	const t = makeT(cliLocale(flags, config?.locale));
 	console.log(t("cli.statusTitle", { repo: repoRoot }));
 	if (!enabled) {
 		console.log(t("cli.statusDisabled"));
 		for (const e of errors) console.log(t("cli.statusConfigError", { err: e }));
+		for (const w of warnings) console.log(t("cli.statusConfigWarning", { warn: w }));
 		return 0;
 	}
+	for (const w of warnings) console.log(t("cli.statusConfigWarning", { warn: w }));
 	const branch = await currentBranch(runner, repoRoot);
 	const c = config;
 	console.log(t("cli.statusEnabled", { pattern: c.featurePattern }));
@@ -177,22 +193,24 @@ async function status(flags, runner) {
 	return 0;
 }
 async function audit(flags) {
-	const repoRoot = await resolveRepo(flags);
+	const repoRoot = await resolveRepo(flags, gitRunner);
 	if (!repoRoot) {
-		console.error(makeT("en")("cli.cannotLocate"));
+		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
 		return 1;
 	}
+	const { config } = await loadConfig(repoRoot);
+	const t = makeT(cliLocale(flags, config?.locale));
 	const lines = flags.lines != null && Number.isFinite(flags.lines) && flags.lines > 0 ? Math.floor(flags.lines) : 20;
 	try {
 		const all = (await readFile(join(stateDir(repoRoot), "audit.jsonl"), "utf8")).split("\n").filter(Boolean);
 		for (const line of all.slice(-lines)) try {
 			const e = JSON.parse(line);
-			console.log(`  ${new Date(e.time).toLocaleString()} ${e.event} ${e.role ?? ""}${e.command ? ` | ${e.command.slice(0, 80)}` : ""}${e.reason ? ` | ${e.reason.slice(0, 60)}` : ""}`);
+			console.log(`  ${new Date(e.time).toISOString()} ${e.event} ${e.role ?? ""}${e.command ? ` | ${e.command.slice(0, 80)}` : ""}${e.reason ? ` | ${e.reason.slice(0, 60)}` : ""}`);
 		} catch {
 			console.log(`  ${line}`);
 		}
 	} catch {
-		console.log(makeT("en")("cli.auditEmpty"));
+		console.log(t("cli.auditEmpty"));
 	}
 	return 0;
 }
@@ -217,8 +235,10 @@ async function check(flags) {
 	const platformFlag = flags.platform ?? "auto";
 	let raw = "";
 	let strict = false;
+	let denyPlatform = "claude";
 	try {
 		raw = flags.command != null ? "" : await readStdin();
+		denyPlatform = platformFlag === "auto" ? detectPlatform(raw) : platformFlag;
 		const payload = flags.command != null ? {
 			command: flags.command,
 			cwd: flags.repo,
@@ -235,21 +255,23 @@ async function check(flags) {
 		if (!loaded.config?.enabled) {
 			if (loaded.errors.length > 0) {
 				const t = makeT("en");
-				if (strict) return emitDeny(platformFlag === "auto" ? detectPlatform(raw) : platformFlag, t("guardStrictConfigBroken.why"), t("guardStrictConfigBroken.next"));
+				if (strict) return emitDeny(denyPlatform, t("guardStrictConfigBroken.why"), t("guardStrictConfigBroken.next"));
 				process.stderr.write(`${t("cli.guardDisabledInvalidConfig", { err: loaded.errors.join("; ") })}\n`);
 			}
 			return 0;
 		}
 		const config = loaded.config;
-		const hookPlatform = platformFlag === "auto" ? detectPlatform(raw) : platformFlag;
-		const locale = resolveLocale(config.locale);
-		const result = await evaluateCommand(payload.command, { repoRoot });
-		if (result.outcome === "deny" && result.reason) return emitDeny(hookPlatform, result.reason.why, result.reason.next, locale);
+		const locale = flags.locale != null ? resolveLocale(flags.locale) : resolveLocale(config.locale);
+		const result = await evaluateCommand(payload.command, {
+			repoRoot,
+			locale
+		});
+		if (result.outcome === "deny" && result.reason) return emitDeny(denyPlatform, result.reason.why, result.reason.next, locale);
 		return 0;
 	} catch (e) {
 		if (strict) {
 			const t = makeT("en");
-			return emitDeny(platformFlag === "auto" ? detectPlatform(raw) : platformFlag, t("guardStrictInternalError.why", { msg: e.message }), t("guardStrictInternalError.next"));
+			return emitDeny(denyPlatform, t("guardStrictInternalError.why", { msg: e.message }), t("guardStrictInternalError.next"));
 		}
 		process.stderr.write(`${makeT("en")("cli.checkInternalError", { msg: e.message })}\n`);
 		return 0;

package/lib/index.d.mts

@@ -1,8 +1,22 @@
 import { t as Runner } from "./repo-DrgptHl1.mjs";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/types.d.ts
-/** 文案语言: 默认 en; 'zh' 切中文 */
-type Locale = 'en' | 'zh';
+/** 文案语言: 默认 en; 'zh' 切中文; 可经 registerLocale 运行时扩展(保留字面量提示的宽字符串) */
+type Locale = 'en' | 'zh' | (string & {});
+//#endregion
+//#region src/i18n.d.ts
+/** 可插值变量(分支名/角色名等) */
+type I18nVars = Record<string, string>;
+/** 单一文案条目: (vars) => 最终文本 */
+type Entry = (v: I18nVars) => string;
+/** 一门语言的文案字典: key 集合必须与内置 en 完全一致(registerLocale / 加载期校验) */
+type Dict = Record<string, Entry>;
+declare const MESSAGE_KEYS: readonly string[];
+/**
+ * 注册一门新语言(运行时扩展点, P2-2): key 集合必须与内置 en 完全一致, 否则抛英文异常。
+ * 注册后 makeT/resolveLocale 即接受该 locale; 未注册的 locale 一律回退英文。
+ */
+declare function registerLocale(name: string, dict: Dict): void;
 //#endregion
 //#region src/index.d.ts
 declare const name = "gitflow-guard";
@@ -19,6 +33,8 @@ interface EvaluateOptions {
   glabRunner?: Runner;
   /** 当前分支(缺省时内部查询) */
   currentBranch?: string | null;
+  /** 覆盖文案 locale(CLI --locale 旗标用, P2-1); 缺省按项目 config.locale 解析 */
+  locale?: Locale;
 }
 interface EvaluateResult {
   outcome: 'allow' | 'deny' | 'skipped';
@@ -45,4 +61,4 @@ declare function evaluateCommand(command: string, opts: EvaluateOptions): Promis
 declare function formatDeny(locale: Locale, why: string, next: string): string;
 declare function apply(ctx: Context, pluginConfig?: PluginConfig): void;
 //#endregion
-export { AuditEntry, EvaluateOptions, EvaluateResult, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };
+export { AuditEntry, type Dict, EvaluateOptions, EvaluateResult, MESSAGE_KEYS, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, i as formatDeny, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-DTg5WMog.mjs";
-export { appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };
+import { a as name, f as MESSAGE_KEYS, i as formatDeny, m as registerLocale, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-BHyQJ6hX.mjs";
+export { MESSAGE_KEYS, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };

package/lib/{src-DTg5WMog.mjs → src-BHyQJ6hX.mjs}

@@ -174,10 +174,30 @@ function classifyGit(args, ctx) {
 	if (sub === "push") return parsePush(rest, ctx);
 	if (sub === "pull") return parsePull(rest);
 	if (sub === "merge") return parseMerge(rest);
-	if (sub === "branch") return parseBranch(rest);
+	if (sub === "branch") return parseBranch(rest, ctx);
 	if (sub === "checkout" || sub === "switch") return parseCheckout(rest);
 	if (sub === "send-pack") return parseSendPack(rest);
 	if (sub === "update-ref") return parseUpdateRef(rest);
+	if (sub === "reset" || sub === "filter-branch") return [{ kind: "ref-move" }];
+	if (sub === "rebase") return parseRebase(rest);
+	if (sub === "commit") return parseCommit(rest);
+	return [{ kind: "other" }];
+}
+/** rebase 移动当前分支 ref; abort/continue/skip 等恢复类旗标不移动(放行, 避免把用户困在中途态) */
+function parseRebase(args) {
+	const RESUME = /* @__PURE__ */ new Set([
+		"--abort",
+		"--continue",
+		"--skip",
+		"--quit",
+		"--edit-todo"
+	]);
+	if (args.some((a) => RESUME.has(a))) return [{ kind: "other" }];
+	return [{ kind: "ref-move" }];
+}
+/** commit 仅 --amend 改写当前分支 tip; 普通提交不移动既有 ref */
+function parseCommit(args) {
+	if (args.some((a) => a === "--amend")) return [{ kind: "ref-move" }];
 	return [{ kind: "other" }];
 }
 /** 剥离子命令前的全局选项(-C <path> / -c <k=v> / --git-dir 等), 否则 git -C . push 会被判 other */
@@ -388,12 +408,60 @@ function parseMerge(args) {
 		source: args.find((a, i) => !a.startsWith("-") && args[i - 1] !== "-m" && args[i - 1] !== "--message") ?? null
 	}];
 }
-function parseBranch(args) {
-	const [flag, name] = args;
-	if ((flag === "-d" || flag === "-D" || flag === "--delete") && name && !name.startsWith("-")) return [{
-		kind: "branch-delete",
-		branch: name,
-		force: flag === "-D"
+/**
+* git branch 全旗标扫描(旧实现只读 args[0..1], `-d --force develop` 这类组合长旗标会漏):
+* - 删除(-d/-D/--delete, 可与 --force 组合): 逐个分支名 → branch-delete
+* - 改名(-m/-M/--move): 移动受保护 ref(源)或覆盖受保护名(目标)→ 按 ref-update 同级处理
+* - 强制复位(-f/--force 单独使用): git branch -f <name> <commit> 静默移动分支指针 → ref-update
+*/
+function parseBranch(args, ctx) {
+	let deleteFlag = false;
+	let force = false;
+	let move = false;
+	const names = [];
+	for (const a of args) if (a.startsWith("--")) {
+		if (a === "--delete") deleteFlag = true;
+		else if (a === "--force") force = true;
+		else if (a === "--move") move = true;
+	} else if (a.startsWith("-") && a.length > 1) {
+		for (const ch of a.slice(1)) if (ch === "d") deleteFlag = true;
+		else if (ch === "D") {
+			deleteFlag = true;
+			force = true;
+		} else if (ch === "m") move = true;
+		else if (ch === "M") {
+			move = true;
+			force = true;
+		} else if (ch === "f") force = true;
+	} else names.push(a);
+	if (move) {
+		const from = names.length >= 2 ? names[0] : ctx.currentBranch ?? null;
+		const to = names.length >= 1 ? names[names.length - 1] : null;
+		const out = [];
+		if (from != null) out.push({
+			kind: "ref-update",
+			branch: from,
+			delete: false
+		});
+		if (to != null && to !== from) out.push({
+			kind: "ref-update",
+			branch: to,
+			delete: false
+		});
+		return out.length > 0 ? out : [{ kind: "other" }];
+	}
+	if (deleteFlag) {
+		if (names.length === 0) return [{ kind: "other" }];
+		return names.map((branch) => ({
+			kind: "branch-delete",
+			branch,
+			force
+		}));
+	}
+	if (force && names.length >= 1) return [{
+		kind: "ref-update",
+		branch: names[0],
+		delete: false
 	}];
 	return [{ kind: "other" }];
 }
@@ -444,166 +512,6 @@ function guardSub(args) {
 	return "other";
 }
 //#endregion
-//#region src/config.ts
-const CONFIG_FILE = "gitflow-guard.config.json";
-/** 默认配置(分支角色必须由项目显式配置, 无默认) */
-const DEFAULT_CONFIG = {
-	enabled: false,
-	featurePattern: "feature/[\\w-]+",
-	ci: { enabled: true },
-	locale: "en"
-};
-const REGEX_CHARS = /[\\^$.*+?()[\]{}|]/;
-/** 一条分支条目: 含正则元字符按正则对待, 否则精确匹配 */
-function matchBranchSpec(branch, spec) {
-	if (REGEX_CHARS.test(spec)) try {
-		return new RegExp(`^(?:${spec})$`).test(branch);
-	} catch {
-		return false;
-	}
-	return branch === spec;
-}
-/** 判断分支是否命中某个角色(任一分支条目) */
-function roleMatches(branch, role) {
-	if (!branch) return false;
-	return role.branches.some((spec) => matchBranchSpec(branch, spec));
-}
-/** 规范化用户输入的某个角色: 数组 或 {branches:[...], update?, mergeBy?} */
-function normalizeRole(raw, defaultUpdate, defaultMergeBy) {
-	const errors = [];
-	let arr;
-	let update = void 0;
-	let mergeBy = void 0;
-	if (Array.isArray(raw)) arr = raw;
-	else if (typeof raw === "object" && raw !== null) {
-		const o = raw;
-		arr = o.branches;
-		update = o.update;
-		mergeBy = o.mergeBy;
-	} else return {
-		role: { branches: [] },
-		errors: ["Branch role must be an array or { branches: [...] }"]
-	};
-	if (!Array.isArray(arr) || arr.length === 0 || !arr.every((x) => typeof x === "string" && x !== "")) errors.push("branches must be a non-empty array of strings");
-	const role = { branches: (Array.isArray(arr) ? arr : []).filter((x) => typeof x === "string" && x !== "") };
-	if (update === void 0 || update === "pr" || update === "flexible") role.update = update === void 0 ? defaultUpdate : update;
-	else errors.push("update must be \"pr\" or \"flexible\"");
-	if (mergeBy === void 0 || mergeBy === "user" || mergeBy === "anyone") role.mergeBy = mergeBy === void 0 ? defaultMergeBy : mergeBy;
-	else errors.push("mergeBy must be \"user\" or \"anyone\"");
-	return {
-		role,
-		errors
-	};
-}
-/** 合并默认值并校验; 任何校验错误都会导致未启用(strict 位仍从原文提取, 供 fail-closed 判定) */
-function mergeConfig(raw) {
-	const errors = [];
-	if (typeof raw !== "object" || raw === null) return {
-		config: null,
-		errors: ["Config file must be a JSON object"]
-	};
-	const r = raw;
-	const strict = r.strict === true ? true : r.strict === false ? false : void 0;
-	if (r.strict !== void 0 && typeof r.strict !== "boolean") errors.push("strict must be a boolean");
-	const config = {
-		...DEFAULT_CONFIG,
-		ci: { ...DEFAULT_CONFIG.ci },
-		branches: { integration: {
-			branches: [],
-			update: "pr",
-			mergeBy: "anyone"
-		} }
-	};
-	if (typeof r.enabled === "boolean") config.enabled = r.enabled;
-	if (typeof r.featurePattern === "string" && r.featurePattern !== "") config.featurePattern = r.featurePattern;
-	if (r.locale === "en" || r.locale === "zh") config.locale = r.locale;
-	else if (r.locale !== void 0) errors.push("locale must be \"en\" or \"zh\"");
-	const b = r.branches ?? {};
-	if ("integration" in b) {
-		const { role, errors: e } = normalizeRole(b.integration, "pr", "anyone");
-		config.branches.integration = role;
-		errors.push(...e);
-	} else errors.push("branches.integration is required");
-	if (b.preview !== void 0) {
-		const { role, errors: e } = normalizeRole(b.preview, "pr", "anyone");
-		config.branches.preview = role;
-		errors.push(...e);
-	}
-	if (b.production !== void 0) {
-		const { role, errors: e } = normalizeRole(b.production, "pr", "user");
-		config.branches.production = role;
-		errors.push(...e);
-	}
-	if (b.archive !== void 0) {
-		const { role, errors: e } = normalizeRole(b.archive, "pr", "user");
-		config.branches.archive = role;
-		errors.push(...e);
-	}
-	const ci = r.ci ?? {};
-	if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
-	if (strict !== void 0) config.strict = strict;
-	errors.push(...validateConfig(config));
-	return {
-		config: errors.length > 0 ? null : config,
-		errors,
-		...strict !== void 0 ? { strict } : {}
-	};
-}
-/** 配置校验: 角色分支重叠 / 正则合法等 */
-function validateConfig(config) {
-	const errors = [];
-	if (config.branches.integration.branches.length === 0) errors.push("branches.integration.branches is required");
-	try {
-		new RegExp(config.featurePattern);
-	} catch {
-		errors.push(`featurePattern is not a valid regex: ${config.featurePattern}`);
-	}
-	const allRoles = [
-		"integration",
-		"preview",
-		"production",
-		"archive"
-	];
-	for (let i = 0; i < allRoles.length; i++) {
-		const a = config.branches[allRoles[i]];
-		if (!a) continue;
-		for (let j = i + 1; j < allRoles.length; j++) {
-			const bb = config.branches[allRoles[j]];
-			if (!bb) continue;
-			if (a.branches.some((s) => bb.branches.includes(s))) errors.push(`branches.${allRoles[i]} and branches.${allRoles[j]} share the same entries`);
-		}
-	}
-	return errors;
-}
-/** 从项目根加载配置; 无文件 = 未启用(opt-in) */
-async function loadConfig(repoRoot) {
-	let text;
-	try {
-		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
-	} catch (e) {
-		if (e.code === "ENOENT") return {
-			config: null,
-			errors: []
-		};
-		return {
-			config: null,
-			errors: [`Failed to read config file: ${e.message}`]
-		};
-	}
-	let raw;
-	try {
-		raw = JSON.parse(text);
-	} catch (e) {
-		const strict = /"strict"\s*:\s*true/.test(text) || void 0;
-		return {
-			config: null,
-			errors: [`Failed to read config file: ${e.message}`],
-			...strict ? { strict } : {}
-		};
-	}
-	return mergeConfig(raw);
-}
-//#endregion
 //#region src/i18n.ts
 const en = {
 	"role.integration": () => "integration branch",
@@ -617,6 +525,8 @@ const en = {
 	"denyDeleteOrForce.next": () => "Delete/force-push on a feature branch outside the protected branches; protected branches are managed by you.",
 	"refUpdateProtected.why": (v) => `Protected branch "${v.branch}" forbids direct ref updates (update-ref)`,
 	"refUpdateProtected.next": () => "Update protected branches via PR/MR; they are managed by you.",
+	"refMoveProtected.why": () => "Rewriting history on a protected branch (reset / rebase / commit --amend / filter-branch) is not allowed",
+	"refMoveProtected.next": () => "Do history rewrites on a feature branch; protected branches advance via PR/MR and are managed by you.",
 	"pushAll.why": () => "--all/--mirror push would include protected branches",
 	"pushAll.next": () => "Push branch by branch with an explicit refspec.",
 	"pushDetached.why": () => "Cannot determine the push target (detached HEAD?)",
@@ -650,6 +560,7 @@ const en = {
 	"cli.statusTitle": (v) => `[gitflow-guard] status — ${v.repo}`,
 	"cli.statusDisabled": () => "Config: not enabled (no gitflow-guard.config.json or enabled=false)",
 	"cli.statusConfigError": (v) => `  config error: ${v.err}`,
+	"cli.statusConfigWarning": (v) => `  config warning: ${v.warn}`,
 	"cli.statusEnabled": (v) => `Config: enabled | featurePattern: ${v.pattern}`,
 	"cli.statusIntegration": (v) => `Integration: ${v.list} (update=${v.mode})`,
 	"cli.statusPreview": (v) => `Preview: ${v.list} (update=${v.mode})`,
@@ -668,13 +579,14 @@ const en = {
 	"usage.text": () => `gitflow-guard — GitFlow guard CLI
 
 Usage:
-  gitflow-guard status [--repo <path>]
-  gitflow-guard audit [--lines <count>] [--repo <path>]
-  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>]
+  gitflow-guard status [--repo <path>] [--locale <en|zh>]
+  gitflow-guard audit [--lines <count>] [--repo <path>] [--locale <en|zh>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>] [--locale <en|zh>]
   gitflow-guard --help
 
 Notes:
   status/audit are read-only; the agent can self-inspect.
+  --locale overrides the message language for this invocation (flag > project config > English).
   check reads the hook payload on stdin (platform-specific protocol: claude/opencode exit 2,
   codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.`
 };
@@ -690,6 +602,8 @@ const zh = {
 	"denyDeleteOrForce.next": () => "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理",
 	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref)`,
 	"refUpdateProtected.next": () => "请通过 PR/MR 更新受保护分支; 受保护分支由用户亲手管理",
+	"refMoveProtected.why": () => "受保护分支禁止本地改写历史(reset / rebase / commit --amend / filter-branch)",
+	"refMoveProtected.next": () => "历史改写请在 feature 分支上进行; 受保护分支仅经 PR/MR 推进, 由用户亲手管理",
 	"pushAll.why": () => "--all/--mirror 推送会包含受保护分支",
 	"pushAll.next": () => "请逐分支推送并显式指定 refspec",
 	"pushDetached.why": () => "无法确定推送目标分支(可能处于 detached HEAD)",
@@ -723,6 +637,7 @@ const zh = {
 	"cli.statusTitle": (v) => `[gitflow-guard] status — ${v.repo}`,
 	"cli.statusDisabled": () => "配置: 未启用(不存在 gitflow-guard.config.json 或 enabled=false)",
 	"cli.statusConfigError": (v) => `  配置错误: ${v.err}`,
+	"cli.statusConfigWarning": (v) => `  配置警告: ${v.warn}`,
 	"cli.statusEnabled": (v) => `配置: 已启用 | featurePattern: ${v.pattern}`,
 	"cli.statusIntegration": (v) => `集成分支: ${v.list} (update=${v.mode})`,
 	"cli.statusPreview": (v) => `预览分支: ${v.list} (update=${v.mode})`,
@@ -741,24 +656,38 @@ const zh = {
 	"usage.text": () => `gitflow-guard — GitFlow 流程守卫 CLI
 
 用法:
-  gitflow-guard status [--repo <路径>]
-  gitflow-guard audit [--lines <数量>] [--repo <路径>]
-  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>]
+  gitflow-guard status [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard audit [--lines <数量>] [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>] [--locale <en|zh>]
   gitflow-guard --help
 
 说明:
   status/audit 只读, agent 可自查。
+  --locale 可临时覆盖本次调用的文案语言(旗标 > 项目配置 > 英文)。
   check 读 stdin hook payload 做门禁(平台协议: claude/opencode exit 2, codex/antigravity stdout JSON),
   供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。`
 };
+/** 内置文案注册表: en 为兜底语言; 下游可经 registerLocale 追加 */
+const dicts = /* @__PURE__ */ new Map([["en", en], ["zh", zh]]);
 const MESSAGE_KEYS = Object.keys(en);
-/** key 合法性与 en/zh 双字典完整性检查(开发期一次) */
-if (Object.keys(zh).length !== MESSAGE_KEYS.length || MESSAGE_KEYS.some((k) => !(k in zh))) throw new Error("i18n: en/zh 字典键不一致");
+/** 字典键一致性校验(与内置 en 完全一致), 失败抛英文异常(P0-2: 异常信息遵循语言规范) */
+function assertDictKeys(name, dict) {
+	if (Object.keys(dict).length !== MESSAGE_KEYS.length || MESSAGE_KEYS.some((k) => !(k in dict))) throw new Error(`i18n: locale "${name}" dictionary keys mismatch the built-in "en" dictionary`);
+}
+assertDictKeys("zh", zh);
 /**
-* 生成翻译函数。未知 key 回退英文原文(开发/防御性)。
+* 注册一门新语言(运行时扩展点, P2-2): key 集合必须与内置 en 完全一致, 否则抛英文异常。
+* 注册后 makeT/resolveLocale 即接受该 locale; 未注册的 locale 一律回退英文。
+*/
+function registerLocale(name, dict) {
+	assertDictKeys(name, dict);
+	dicts.set(name, dict);
+}
+/**
+* 生成翻译函数。未注册 locale / 未知 key 均回退英文(开发/防御性)。
 */
 function makeT(locale) {
-	const dict = locale === "zh" ? zh : en;
+	const dict = dicts.get(locale) ?? en;
 	return (key, vars = {}) => {
 		const entry = dict[key] ?? en[key];
 		if (!entry) return key;
@@ -769,9 +698,182 @@ function makeT(locale) {
 		}
 	};
 }
-/** 解析配置里的 locale 值: 仅 'zh' 视为中文, 其余(含未定义)一律英文 */
+/** 解析配置里的 locale 值: 白名单语义 = 已注册语言原样通过, 其余(含未定义)一律英文(P2-2 后白名单随注册表扩展) */
 function resolveLocale(v) {
-	return v === "zh" ? "zh" : "en";
+	return typeof v === "string" && dicts.has(v) ? v : "en";
+}
+//#endregion
+//#region src/config.ts
+const CONFIG_FILE = "gitflow-guard.config.json";
+/** 默认配置(分支角色必须由项目显式配置, 无默认) */
+const DEFAULT_CONFIG = {
+	enabled: false,
+	featurePattern: "feature/[\\w-]+",
+	ci: { enabled: true },
+	locale: "en"
+};
+const REGEX_CHARS = /[\\^$.*+?()[\]{}|]/;
+/** 一条分支条目: 含正则元字符按正则对待, 否则精确匹配 */
+function matchBranchSpec(branch, spec) {
+	if (REGEX_CHARS.test(spec)) try {
+		return new RegExp(`^(?:${spec})$`).test(branch);
+	} catch {
+		return false;
+	}
+	return branch === spec;
+}
+/** 判断分支是否命中某个角色(任一分支条目) */
+function roleMatches(branch, role) {
+	if (!branch) return false;
+	return role.branches.some((spec) => matchBranchSpec(branch, spec));
+}
+/** 规范化用户输入的某个角色: 数组 或 {branches:[...], update?, mergeBy?} */
+function normalizeRole(raw, roleName, defaultUpdate, defaultMergeBy) {
+	const errors = [];
+	let arr;
+	let update = void 0;
+	let mergeBy = void 0;
+	if (Array.isArray(raw)) arr = raw;
+	else if (typeof raw === "object" && raw !== null) {
+		const o = raw;
+		arr = o.branches;
+		update = o.update;
+		mergeBy = o.mergeBy;
+	} else return {
+		role: { branches: [] },
+		errors: ["Branch role must be an array or { branches: [...] }"]
+	};
+	if (!Array.isArray(arr) || arr.length === 0 || !arr.every((x) => typeof x === "string" && x !== "")) errors.push("branches must be a non-empty array of strings");
+	const role = { branches: (Array.isArray(arr) ? arr : []).filter((x) => typeof x === "string" && x !== "") };
+	for (const spec of role.branches) try {
+		new RegExp(`^(?:${spec})$`);
+	} catch {
+		errors.push(`branches.${roleName} entry is not a valid regex: ${spec}`);
+	}
+	if (update === void 0 || update === "pr" || update === "flexible") role.update = update === void 0 ? defaultUpdate : update;
+	else errors.push("update must be \"pr\" or \"flexible\"");
+	if (mergeBy === void 0 || mergeBy === "user" || mergeBy === "anyone") role.mergeBy = mergeBy === void 0 ? defaultMergeBy : mergeBy;
+	else errors.push("mergeBy must be \"user\" or \"anyone\"");
+	return {
+		role,
+		errors
+	};
+}
+/** 合并默认值并校验; 任何校验错误都会导致未启用(strict 位仍从原文提取, 供 fail-closed 判定) */
+function mergeConfig(raw) {
+	const errors = [];
+	const warnings = [];
+	if (typeof raw !== "object" || raw === null) return {
+		config: null,
+		errors: ["Config file must be a JSON object"],
+		warnings
+	};
+	const r = raw;
+	const strict = r.strict === true ? true : r.strict === false ? false : void 0;
+	if (r.strict !== void 0 && typeof r.strict !== "boolean") errors.push("strict must be a boolean");
+	const config = {
+		...DEFAULT_CONFIG,
+		ci: { ...DEFAULT_CONFIG.ci },
+		branches: { integration: {
+			branches: [],
+			update: "pr",
+			mergeBy: "anyone"
+		} }
+	};
+	if (typeof r.enabled === "boolean") config.enabled = r.enabled;
+	if (typeof r.featurePattern === "string" && r.featurePattern !== "") config.featurePattern = r.featurePattern;
+	if (typeof r.locale === "string" && r.locale !== "") {
+		config.locale = r.locale;
+		if (resolveLocale(r.locale) !== r.locale) warnings.push(`unknown locale "${r.locale}"; falling back to en`);
+	} else if (r.locale !== void 0) errors.push("locale must be a string");
+	const b = r.branches ?? {};
+	if ("integration" in b) {
+		const { role, errors: e } = normalizeRole(b.integration, "integration", "pr", "anyone");
+		config.branches.integration = role;
+		errors.push(...e);
+	} else errors.push("branches.integration is required");
+	if (b.preview !== void 0) {
+		const { role, errors: e } = normalizeRole(b.preview, "preview", "pr", "anyone");
+		config.branches.preview = role;
+		errors.push(...e);
+	}
+	if (b.production !== void 0) {
+		const { role, errors: e } = normalizeRole(b.production, "production", "pr", "user");
+		config.branches.production = role;
+		errors.push(...e);
+	}
+	if (b.archive !== void 0) {
+		const { role, errors: e } = normalizeRole(b.archive, "archive", "pr", "user");
+		config.branches.archive = role;
+		errors.push(...e);
+	}
+	const ci = r.ci ?? {};
+	if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
+	if (strict !== void 0) config.strict = strict;
+	errors.push(...validateConfig(config));
+	return {
+		config: errors.length > 0 ? null : config,
+		errors,
+		warnings,
+		...strict !== void 0 ? { strict } : {}
+	};
+}
+/** 配置校验: 角色分支重叠等(角色条目正则合法性已在 normalizeRole 预编译报错) */
+function validateConfig(config) {
+	const errors = [];
+	if (config.branches.integration.branches.length === 0) errors.push("branches.integration.branches is required");
+	try {
+		new RegExp(config.featurePattern);
+	} catch {
+		errors.push(`featurePattern is not a valid regex: ${config.featurePattern}`);
+	}
+	const allRoles = [
+		"integration",
+		"preview",
+		"production",
+		"archive"
+	];
+	for (let i = 0; i < allRoles.length; i++) {
+		const a = config.branches[allRoles[i]];
+		if (!a) continue;
+		for (let j = i + 1; j < allRoles.length; j++) {
+			const bb = config.branches[allRoles[j]];
+			if (!bb) continue;
+			if (a.branches.some((s) => bb.branches.includes(s))) errors.push(`branches.${allRoles[i]} and branches.${allRoles[j]} share the same entries`);
+		}
+	}
+	return errors;
+}
+/** 从项目根加载配置; 无文件 = 未启用(opt-in) */
+async function loadConfig(repoRoot) {
+	let text;
+	try {
+		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+	} catch (e) {
+		if (e.code === "ENOENT") return {
+			config: null,
+			errors: [],
+			warnings: []
+		};
+		return {
+			config: null,
+			errors: [`Failed to read config file: ${e.message}`],
+			warnings: []
+		};
+	}
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (e) {
+		const strict = /"strict"\s*:\s*true/.test(text) || void 0;
+		return {
+			config: null,
+			errors: [`Failed to read config file: ${e.message}`],
+			warnings: [],
+			...strict ? { strict } : {}
+		};
+	}
+	return mergeConfig(raw);
 }
 //#endregion
 //#region src/gate.ts
@@ -818,6 +920,7 @@ function decide(classified, facts, config, t = defaultT) {
 		case "pr-merge": return decidePrMerge(classified, facts, config, t);
 		case "branch-delete": return isProtected(roleOfBranch(classified.branch, config)) ? deny(t("denyDeleteOrForce.why", { branch: classified.branch ?? "" }), t("denyDeleteOrForce.next")) : { kind: "allow" };
 		case "ref-update": return classified.branch != null && isProtected(roleOfBranch(classified.branch, config)) ? deny(t("refUpdateProtected.why", { branch: classified.branch }), t("refUpdateProtected.next")) : { kind: "allow" };
+		case "ref-move": return isProtected(roleOfBranch(facts.currentBranch, config)) ? deny(t("refMoveProtected.why"), t("refMoveProtected.next")) : { kind: "allow" };
 		case "guard-cli": return { kind: "allow" };
 		case "checkout": return { kind: "allow" };
 		default: return { kind: "allow" };
@@ -1030,7 +1133,7 @@ async function evaluateCommand(command, opts) {
 		segmentCount: 0,
 		locale: "en"
 	};
-	const locale = resolveLocale(config.locale);
+	const locale = opts.locale != null ? resolveLocale(opts.locale) : resolveLocale(config.locale);
 	const t = makeT(locale);
 	const branch = opts.currentBranch ?? await currentBranch(runner, opts.repoRoot);
 	const env = {
@@ -1133,10 +1236,10 @@ function apply(ctx, pluginConfig = {}) {
 			};
 			return next();
 		} catch (e) {
-			ctx.logger?.warn?.(`gitflow-guard: 门禁内部错误, 已放行: ${e.message}`);
+			ctx.logger?.warn?.(`gitflow-guard: gate internal error, allowed through: ${e.message}`);
 			return next();
 		}
 	});
 }
 //#endregion
-export { name as a, findRepoRoot as c, resolveLocale as d, loadConfig as f, formatDeny as i, gitRunner as l, classify as m, apply as n, stateDir as o, roleMatches as p, evaluateCommand as r, currentBranch as s, appendAudit as t, makeT as u };
+export { name as a, findRepoRoot as c, roleMatches as d, MESSAGE_KEYS as f, classify as g, resolveLocale as h, formatDeny as i, gitRunner as l, registerLocale as m, apply as n, stateDir as o, makeT as p, evaluateCommand as r, currentBranch as s, appendAudit as t, loadConfig as u };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity) — integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "main": "lib/index.mjs",
   "types": "lib/index.d.mts",
   "exports": {
@@ -42,6 +43,13 @@
     "type": "git",
     "url": "https://github.com/FeatureAgents/AgentsGitFlowController.git"
   },
+  "bugs": {
+    "url": "https://github.com/FeatureAgents/AgentsGitFlowController/issues"
+  },
+  "homepage": "https://github.com/FeatureAgents/AgentsGitFlowController#readme",
+  "engines": {
+    "node": ">=22"
+  },
   "dsh": {
     "bundle": {
       "patch": "./patch.yml"

package/patch.yml

@@ -1,5 +1,5 @@
-# agents-gitflow-guard 插件挂载层(dsh plugin add 后自动成为 profile 层)
-# 行配置可在 profile 的 cordis.patch.yml 中按 id 覆盖
+# agents-gitflow-guard DSH mount layer (applied into the profile after `dsh plugin add`)
+# Rows here can be overridden per-id in the profile's cordis.patch.yml
 
 - insert:
     - id: gitflow-guard