agents-gitflow-guard 0.0.10 → 0.0.12

package/README.md

@@ -42,7 +42,7 @@ 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.12
 ```
 
 > **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).
@@ -256,7 +256,8 @@ 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
 }
 ```
@@ -264,9 +265,12 @@ 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.
+- **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.
 
 ---
 
@@ -299,7 +303,7 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 **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.12    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -391,7 +395,9 @@ No. Add only the roles your flow actually has. A solo repo with just `develop` c
 
 No, and it is important that you don't treat it as one. It is a workflow guard: it makes an agreed process mechanically enforceable. Text-based command recognition is inherently best-effort — an agent determined to obfuscate a command can slip past the parser.
 
-But what cannot be bypassed is the **role boundary itself**: merging into a protected role branch (integration / preview / production / archive) requires the configured path (PR/MR, or a human merge for production/archive). If you need real protection against hostile agents, that belongs in branch-protection rules on your hosting service.
+Within its supported command forms, the role boundary is enforced locally: merging into a protected role branch (integration / preview / production / archive) requires the configured path (PR/MR, or a human merge for production/archive). Standard obfuscation wrappers are classified and blocked — shell wrappers (`sh -c` / `bash -lc`), subshells and backtick/`$()` nesting, `env`/`command`/`nohup`/`xargs` prefixes and `VAR=x` assignments, absolute paths, pipelines and `||` tails, git global options (`-C .`, `--git-dir=…`), wildcard refspecs (`refs/heads/*:refs/heads/*`), `git pull` used as fetch+merge, and the `send-pack`/`update-ref` plumbing. The executable adversarial corpus lives in `tests/accuracy-audit.spec.ts`.
+
+What remains **locally non-defensible**: direct forge-API calls (`gh api repos/…/pulls/N/merge`, `curl`) and commands inside interpreter subprocesses (`node -e "child_process.exec('git push …')"`); arbitrarily deep quoting or encoding stays best-effort by nature. The real, non-bypassable boundary lives in branch-protection rules on your hosting service. Use both — treat this guard as instant feedback and audit trail, not as a security boundary.
 
 ---
 
@@ -403,7 +409,7 @@ Because the gate classifies those as **user-only** actions. An agent may create
 
 ### Do I need the `gh` or `glab` CLI?
 
-No. They are optional adapters used only to resolve what a `pr merge` / `mr merge` is targeting, so the gate can tell "merge into integration/preview" (okay) from "merge into production/archive" (blocked). Without them, the plugin takes a conservative path — it refuses when it can't confirm the target — and everything else works the same. The core enforcement never touches a hosting service, which is why it works identically on GitHub, GitLab, self-hosted, or offline.
+No. They are optional adapters used only to resolve what a `pr merge` / `mr merge` is targeting, so the gate can tell "merge into integration/preview" (okay) from "merge into production/archive" (blocked). When neither CLI can confirm the target — missing, unauthenticated, offline, or the query fails — the gate **refuses the merge**, even when run from a feature branch: that PR could actually point at production/archive. Retry once the CLI works, or let the user click merge. Everything else works the same. The core enforcement never touches a hosting service, which is why it works identically on GitHub, GitLab, self-hosted, or offline.
 
 ---
 
@@ -417,7 +423,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.
 
@@ -479,7 +485,7 @@ npm install
 npm test          # unit tests: classify / gate / config / cli / repo / platform
 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.

package/README.zh.md

@@ -41,7 +41,7 @@
 # 安装最新版
 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.12
 ```
 
 > **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
@@ -253,7 +253,8 @@ 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 作参考日志
 }
 ```
@@ -261,9 +262,12 @@ 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"` 即生效。
+- **未注册语言**:拦截路径对未注册的 `"locale"` 静默回退英文(设计如此——hook 不因文案缺失卡死),笔误因此容易被忽略;一行告警在 `gitflow-guard status` 中可见。
 - **校验**:`integration` 必填;角色条目重叠会被拒;非法正则会报错。**任何错误都会让该项目的插件禁用并上报**(而不是用半吊子配置)。
+- **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。文件不存在或显式 `enabled: false` 两种模式下都保持静默。
 
 ---
 
@@ -296,7 +300,7 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 **从 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.12    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -388,7 +392,9 @@ hooks:
 
 不是,请注意别把它当安全工具。它是工作流守卫:把既定流程变成可机制执行的东西。基于文本的命令识别天然是尽力而为——铁心混淆命令的 agent 可以绕过解析器。
 
-但**角色边界本身**无法绕过:合入受保护角色分支(integration / preview / production / archive)必须走配置好的路径(PR/MR,或生产/归档的人工合并)。要真正防恶意 agent,那属于你托管服务的分支保护设置。
+在其支持的命令形态内,角色边界在本地强制生效:合入受保护角色分支(integration / preview / production / archive)必须走配置好的路径(PR/MR,或生产/归档的人工合并)。常见混淆包装已纳入分类与拦截——shell 包装(`sh -c` / `bash -lc`)、子 shell 与反引号/`$()` 内嵌、`env`/`command`/`nohup`/`xargs` 前缀与 `VAR=x` 赋值、绝对路径、管道与 `||` 后半段、git 全局选项(`-C .`、`--git-dir=…`)、通配 refspec(`refs/heads/*:refs/heads/*`)、当 fetch+merge 用的 `git pull`,以及 `send-pack`/`update-ref` 等 plumbing。可执行对抗语料见 `tests/accuracy-audit.spec.ts`。
+
+已知**本地不可防**的通道:直连 forge API(`gh api repos/…/pulls/N/merge`、`curl`)与解释器子进程内嵌(`node -e "child_process.exec('git push …')"`);任意深度的引号/编码变换天然只能尽力而为。真正不可绕过的边界在你托管服务的分支保护设置。两边都用——把本守卫当作即时反馈与审计留痕,而不是安全边界。
 
 ---
 
@@ -400,7 +406,7 @@ hooks:
 
 ### 必须装 `gh` 或 `glab` CLI 吗?
 
-不用。它们只是可选适配器,用来解析 `pr merge` / `mr merge` 到底指向哪个分支,好让门禁区分"合入 integration/preview"(放行)与"合入 production/archive"(拦截)。没有时插件走保守路径——无法确认目标就拒绝——其余一切照常。核心校验不碰任何托管服务,所以它在 GitHub、GitLab、自托管或离线环境里行为一致。
+不用。它们只是可选适配器,用来解析 `pr merge` / `mr merge` 到底指向哪个分支,好让门禁区分"合入 integration/preview"(放行)与"合入 production/archive"(拦截)。当两个 CLI 都无法确认目标——未安装、未认证、离线或查询失败——门禁**一律拒绝合并**,即使在 feature 分支上执行也照拦:该 PR 可能实际指向生产/归档分支。等 CLI 可用后重试,或由用户亲手点合并。其余一切照常。核心校验不碰任何托管服务,所以它在 GitHub、GitLab、自托管或离线环境里行为一致。
 
 ---
 
@@ -414,7 +420,7 @@ hooks:
 
 ### 配置写错了会怎样?
 
-插件偏好 fail-closed:任何校验错误都会让该项目的守卫禁用并上报错误,半吊子配置绝不会意外生效。
+半吊子配置绝不会意外生效:任何校验错误都会让该项目的守卫禁用并上报错误。
 
 常见错误:`integration` 缺失(必填)、同一个分支被配到两个角色里(显式拒绝)、`featurePattern` 写不成合法正则(报错)。失败提示很明确,文件又是一个 JSON 对象,通常三十秒改好。
 
@@ -476,9 +482,10 @@ npm install
 npm test          # 单测: classify / gate / config / cli / repo / platform
 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`)全绿后才算完成。
 
 ---
 

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-CeEqUVQP.mjs";
+import { c as findRepoRoot, d as roleMatches, f as makeT, h as classify, i as formatDeny, l as gitRunner, m as resolveLocale, o as stateDir, r as evaluateCommand, s as currentBranch, u as loadConfig } from "./src-CPX1Ks_Z.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;
 }
@@ -205,35 +223,56 @@ function readStdin() {
 		process.stdin.on("error", () => resolve(data));
 	});
 }
+/** 按平台编码并输出 deny, 返回退出码 */
+function emitDeny(platform, why, next, locale = "en") {
+	const enc = encodeDeny(platform, formatDeny(locale, why, next));
+	if (enc.stdout) process.stdout.write(enc.stdout + "\n");
+	if (enc.stderr) process.stderr.write(enc.stderr + "\n");
+	return enc.exitCode;
+}
 /** check: agent hook 门禁。读 stdin hook payload(或 --command), exit 0=放行 / 2=拦截(按平台编码) */
 async function check(flags) {
-	const platform = flags.platform ?? "auto";
+	const platformFlag = flags.platform ?? "auto";
+	let raw = "";
+	let strict = false;
+	let denyPlatform = "claude";
 	try {
-		const raw = flags.command != null ? "" : await readStdin();
+		raw = flags.command != null ? "" : await readStdin();
+		denyPlatform = platformFlag === "auto" ? detectPlatform(raw) : platformFlag;
 		const payload = flags.command != null ? {
 			command: flags.command,
 			cwd: flags.repo,
 			event: "pre"
-		} : extractHookPayload(raw, platform);
+		} : extractHookPayload(raw, platformFlag);
 		if (!payload?.command) return 0;
 		const segments = classify(payload.command);
 		if (segments.length === 0 || segments.every((s) => s.kind === "other")) return 0;
 		const cwd = payload.cwd ?? process.cwd();
 		const repoRoot = flags.repo ?? await findRepoRoot(gitRunner, cwd);
 		if (!repoRoot) return 0;
-		const { config } = await loadConfig(repoRoot);
-		if (!config?.enabled) return 0;
-		const hookPlatform = platform === "auto" ? detectPlatform(raw) : platform;
-		const locale = resolveLocale(config.locale);
-		const result = await evaluateCommand(payload.command, { repoRoot });
-		if (result.outcome === "deny" && result.reason) {
-			const enc = encodeDeny(hookPlatform, formatDeny(locale, result.reason.why, result.reason.next));
-			if (enc.stdout) process.stdout.write(enc.stdout + "\n");
-			if (enc.stderr) process.stderr.write(enc.stderr + "\n");
-			return enc.exitCode;
+		const loaded = await loadConfig(repoRoot);
+		strict = loaded.strict === true || loaded.config?.strict === true;
+		if (!loaded.config?.enabled) {
+			if (loaded.errors.length > 0) {
+				const t = makeT("en");
+				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 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(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,21 @@
 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>;
+/**
+ * 注册一门新语言(运行时扩展点, 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 +32,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 +60,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, 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-CeEqUVQP.mjs";
-export { appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };
+import { a as name, i as formatDeny, n as apply, o as stateDir, p as registerLocale, r as evaluateCommand, t as appendAudit } from "./src-CPX1Ks_Z.mjs";
+export { appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };

package/lib/{src-CeEqUVQP.mjs → src-CPX1Ks_Z.mjs}

@@ -2,11 +2,58 @@ import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { execFile } from "node:child_process";
 //#region src/classify.ts
-/** 拆分命令为多段(&& / 分号 / 换行), 每段独立分类; 引号内的分隔符不算 */
+/** 拆分命令为多段(&& / || / | / 分号 / 换行), 每段独立分类; 引号内的分隔符不算 */
 function classify(command, ctx = {}) {
-	return splitSegments(command).flatMap((seg) => classifySegment(seg, ctx));
+	const { plain, nested } = extractNested(command);
+	return [...splitSegments(plain).flatMap((seg) => classifySegment(seg, ctx)), ...nested.flatMap((n) => classify(n, ctx))];
 }
-/** 引号感知拆分: 保护 "..." 与 '...' 内的 && / ; / 换行 */
+/** 提取反引号与 $() 内层命令文本一并送分类(单引号内不展开, 与 shell 语义一致); 外层文本剥离内嵌段后返回 */
+function extractNested(command) {
+	const nested = [];
+	let plain = "";
+	let inSingle = false;
+	for (let i = 0; i < command.length; i++) {
+		const ch = command[i];
+		if (inSingle) {
+			plain += ch;
+			if (ch === "'") inSingle = false;
+			continue;
+		}
+		if (ch === "'") {
+			inSingle = true;
+			plain += ch;
+			continue;
+		}
+		if (ch === "`") {
+			const end = command.indexOf("`", i + 1);
+			if (end === -1) {
+				plain += ch;
+				continue;
+			}
+			nested.push(command.slice(i + 1, end));
+			i = end;
+			continue;
+		}
+		if (ch === "$" && command[i + 1] === "(") {
+			let depth = 1;
+			let j = i + 2;
+			while (j < command.length && depth > 0) {
+				if (command[j] === "(") depth++;
+				else if (command[j] === ")") depth--;
+				j++;
+			}
+			nested.push(command.slice(i + 2, depth === 0 ? j - 1 : j));
+			i = j - 1;
+			continue;
+		}
+		plain += ch;
+	}
+	return {
+		plain,
+		nested
+	};
+}
+/** 引号感知拆分: 保护 "..." 与 '...' 内的 && / || / | / ; / 换行 */
 function splitSegments(command) {
 	const segments = [];
 	let current = "";
@@ -32,7 +79,12 @@ function splitSegments(command) {
 			i++;
 			continue;
 		}
-		if (ch === ";" || ch === "\n") {
+		if (ch === "|" && command[i + 1] === "|") {
+			push();
+			i++;
+			continue;
+		}
+		if (ch === ";" || ch === "\n" || ch === "|") {
 			push();
 			continue;
 		}
@@ -41,31 +93,128 @@ function splitSegments(command) {
 	push();
 	return segments;
 }
+/** shell 解释器包装(sh/bash/zsh -c "<script>"): 脚本文本整体重分类 */
+const SHELLS = /* @__PURE__ */ new Set([
+	"sh",
+	"bash",
+	"zsh",
+	"dash",
+	"ksh"
+]);
+/** 可剥离的执行前缀(env/nohup/xargs/command 及 VAR=x 赋值) */
+const WRAPPERS = /* @__PURE__ */ new Set([
+	"env",
+	"command",
+	"nohup",
+	"xargs"
+]);
 function classifySegment(segment, ctx) {
-	const tokens = tokenize(segment);
+	const trimmed = segment.trim();
+	const tokens = tokenize(trimmed.startsWith("(") && trimmed.endsWith(")") ? trimmed.slice(1, -1).trim() : trimmed);
 	if (tokens.length === 0) return [{ kind: "other" }];
-	const [cmd, ...rest] = tokens;
-	if (cmd === "git") return classifyGit(rest, ctx);
-	if (cmd === "gh") return classifyGh(rest);
-	if (cmd === "glab") return classifyGlab(rest);
+	return classifyTokens(tokens, ctx);
+}
+/** 分派: 已知命令直接解析; 包装器剥壳后递归(token 只减不增, 必然终止) */
+function classifyTokens(tokens, ctx) {
+	const rawCmd = tokens[0];
+	const cmd = rawCmd.includes("/") ? rawCmd.slice(rawCmd.lastIndexOf("/") + 1) : rawCmd;
+	if (SHELLS.has(cmd)) return classifyShellWrapped(tokens, ctx);
+	if (cmd === "env") return classifyTokens(stripEnvArgs(tokens.slice(1)), ctx);
+	if (WRAPPERS.has(cmd)) return classifyTokens(stripWrapperArgs(tokens.slice(1)), ctx);
+	if (/^[\w-][\w.-]*=/.test(rawCmd)) return classifyTokens(tokens.slice(1), ctx);
+	if (cmd === "git") return classifyGit(tokens.slice(1), ctx);
+	if (cmd === "gh") return classifyGh(tokens.slice(1));
+	if (cmd === "glab") return classifyGlab(tokens.slice(1));
 	if (cmd === "gitflow-guard") return [{
 		kind: "guard-cli",
-		sub: guardSub(rest)
+		sub: guardSub(tokens.slice(1))
 	}];
 	return [{ kind: "other" }];
 }
+/** sh/bash -lc "<script>": 定位 -c(含合并短旗标如 -lc)取脚本文本递归; 取不到按 other 放行 */
+function classifyShellWrapped(tokens, ctx) {
+	for (let i = 1; i < tokens.length; i++) {
+		const a = tokens[i];
+		if (!(a === "-c" || a.startsWith("-") && !a.startsWith("--") && a.includes("c"))) continue;
+		const script = tokens[i + 1];
+		if (script == null) break;
+		return script.length > 0 ? classify(script, ctx) : [{ kind: "other" }];
+	}
+	return [{ kind: "other" }];
+}
+/** env 参数剥离: 旗标与 VAR=x 赋值;-u/--unset 消费下一个参数 */
+function stripEnvArgs(args) {
+	let i = 0;
+	while (i < args.length) {
+		const a = args[i];
+		if (a === "-u" || a === "--unset") {
+			i += args[i + 1] != null ? 2 : 1;
+			continue;
+		}
+		if (a.startsWith("-") || /^[\w-]+=/.test(a)) {
+			i++;
+			continue;
+		}
+		break;
+	}
+	return args.slice(i);
+}
+/** nohup/xargs/command 参数剥离: 旗标、纯数字(xargs -n 2 的值)与 VAR=x */
+function stripWrapperArgs(args) {
+	let i = 0;
+	while (i < args.length && (args[i].startsWith("-") || /^\d+$/.test(args[i]) || /^[\w-]+=/.test(args[i]))) i++;
+	return args.slice(i);
+}
 /** 分词: 引号内的空格不拆分 */
 function tokenize(segment) {
 	return segment.match(/"[^"]*"|'[^']*'|\S+/g)?.map((t) => t.replace(/^['"]|['"]$/g, "")) ?? [];
 }
 function classifyGit(args, ctx) {
-	const [sub, ...rest] = args;
+	const [sub, ...rest] = stripGlobalOptions(args);
 	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 === "checkout" || sub === "switch") return parseCheckout(rest);
+	if (sub === "send-pack") return parseSendPack(rest);
+	if (sub === "update-ref") return parseUpdateRef(rest);
 	return [{ kind: "other" }];
 }
+/** 剥离子命令前的全局选项(-C <path> / -c <k=v> / --git-dir 等), 否则 git -C . push 会被判 other */
+function stripGlobalOptions(args) {
+	const WITH_VALUE = /* @__PURE__ */ new Set([
+		"-C",
+		"-c",
+		"--git-dir",
+		"--work-tree",
+		"--namespace",
+		"--super-prefix"
+	]);
+	const BARE = /* @__PURE__ */ new Set([
+		"--bare",
+		"--no-pager",
+		"--no-optional-locks",
+		"--paginate",
+		"--no-replace-objects",
+		"--literal-pathspecs",
+		"-p",
+		"-P"
+	]);
+	let i = 0;
+	while (i < args.length) {
+		const a = args[i];
+		if (BARE.has(a) || /^--(git-dir|work-tree|namespace|super-prefix)=/.test(a)) {
+			i++;
+			continue;
+		}
+		if (WITH_VALUE.has(a)) {
+			i += 2;
+			continue;
+		}
+		break;
+	}
+	return args.slice(i);
+}
 /** 分支切换: 门禁放行, 分支状态由 evaluateCommand 按段模拟 */
 function parseCheckout(args) {
 	const first = args[0];
@@ -106,47 +255,72 @@ function parsePush(args, ctx) {
 		delete: false,
 		all: true
 	}];
-	const refspecs = nonFlag.slice(1);
-	if (refspecs.length === 0) return [{
+	const [first, second] = nonFlag;
+	if (first == null) return [{
 		kind: "push",
-		dst: ctx.currentBranch ?? null,
+		dst: null,
 		force,
 		delete: false
 	}];
-	return refspecs.map((ref) => {
-		let refForce = force;
-		if (ref.startsWith("+")) {
+	if (second == null) return [{
+		kind: "push",
+		dst: stripRefPrefix(first),
+		force,
+		delete: isDelete
+	}, {
+		kind: "push",
+		dst: null,
+		force,
+		delete: isDelete
+	}];
+	return mapRefspecs(nonFlag.slice(1), {
+		force,
+		delete: isDelete
+	}, ctx);
+}
+/** refspec → push 分类。含 * 视为批量推送(与 --all 同级); HEAD/空 dst 延迟为 null(门禁按模拟分支解析) */
+function mapRefspecs(refspecs, base, ctx) {
+	return refspecs.map((raw) => {
+		let refForce = base.force;
+		if (raw.startsWith("+")) {
 			refForce = true;
-			ref = ref.slice(1);
+			raw = raw.slice(1);
 		}
-		if (ref.startsWith(":")) return {
+		if (raw.includes("*")) return {
+			kind: "push",
+			dst: null,
+			force: refForce,
+			delete: false,
+			all: true
+		};
+		if (raw.startsWith(":")) return {
 			kind: "push",
-			dst: stripRefPrefix(ref.slice(1)) || null,
+			dst: stripRefPrefix(raw.slice(1)) || null,
 			force: refForce,
 			delete: true
 		};
-		const colon = ref.indexOf(":");
+		const colon = raw.indexOf(":");
 		if (colon >= 0) {
-			const deleteTarget = ref.endsWith(":");
-			const dst = deleteTarget ? ref.slice(colon + 1, ref.length - 1) || ref.slice(0, colon) : ref.slice(colon + 1);
+			const deleteTarget = raw.endsWith(":");
+			const dst = deleteTarget ? raw.slice(colon + 1, raw.length - 1) || raw.slice(0, colon) : raw.slice(colon + 1);
 			return {
 				kind: "push",
 				dst: dst ? stripRefPrefix(dst) : null,
 				force: refForce,
-				delete: deleteTarget || isDelete
+				delete: deleteTarget || base.delete
 			};
 		}
-		if (ref === "HEAD") return {
+		if (raw === "HEAD") return {
 			kind: "push",
-			dst: ctx.currentBranch ?? null,
+			dst: null,
 			force: refForce,
-			delete: isDelete
+			delete: base.delete
 		};
 		return {
 			kind: "push",
-			dst: stripRefPrefix(ref),
+			dst: stripRefPrefix(raw),
 			force: refForce,
-			delete: isDelete
+			delete: base.delete
 		};
 	});
 }
@@ -154,6 +328,59 @@ function parsePush(args, ctx) {
 function stripRefPrefix(branch) {
 	return branch.startsWith("refs/heads/") ? branch.slice(11) : branch;
 }
+/** git pull = fetch+merge: 取最后一个非 flag 参数为远端分支名(source), 交给本地合入门禁; 无 refspec 时 source=null(同步上游语义) */
+function parsePull(args) {
+	const nonFlags = args.filter((a) => !a.startsWith("-"));
+	const last = nonFlags[nonFlags.length - 1];
+	return [{
+		kind: "local-merge",
+		source: nonFlags.length >= 2 && last ? last.replace(/^\+/, "") : null
+	}];
+}
+/** git send-pack(push 的底层等价物): 首个非 flag 是 host:path, 其后 refspec 按推送语义分类 */
+function parseSendPack(args) {
+	let force = false;
+	let all = false;
+	const nonFlag = [];
+	for (const a of args) if (a === "-f" || a === "--force") force = true;
+	else if (a === "--all") all = true;
+	else if (!a.startsWith("-")) nonFlag.push(a);
+	if (all) return [{
+		kind: "push",
+		dst: null,
+		force,
+		delete: false,
+		all: true
+	}];
+	const refspecs = nonFlag.slice(1);
+	if (refspecs.length === 0) return [{ kind: "other" }];
+	return mapRefspecs(refspecs, {
+		force,
+		delete: false
+	});
+}
+/** git update-ref 直改 refs(plumbing): 提取目标 ref(剥 refs/heads/ 前缀供角色比对); -d 为删除 */
+function parseUpdateRef(args) {
+	let isDelete = false;
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === "-d") {
+			isDelete = true;
+			continue;
+		}
+		if (a === "-m" || a === "--message") {
+			i++;
+			continue;
+		}
+		if (a.startsWith("-")) continue;
+		return [{
+			kind: "ref-update",
+			branch: stripRefPrefix(a),
+			delete: isDelete
+		}];
+	}
+	return [{ kind: "other" }];
+}
 function parseMerge(args) {
 	if (args.some((a) => a === "--abort")) return [{ kind: "other" }];
 	return [{
@@ -217,150 +444,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
-	};
-}
-/** 合并默认值并校验; 任何校验错误都会导致未启用 */
-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 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;
-	errors.push(...validateConfig(config));
-	return {
-		config: errors.length > 0 ? null : config,
-		errors
-	};
-}
-/** 配置校验: 角色分支重叠 / 正则合法等 */
-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) {
-	try {
-		const text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
-		return mergeConfig(JSON.parse(text));
-	} catch (e) {
-		if (e.code === "ENOENT") return {
-			config: null,
-			errors: []
-		};
-		return {
-			config: null,
-			errors: [`Failed to read config file: ${e.message}`]
-		};
-	}
-}
-//#endregion
 //#region src/i18n.ts
 const en = {
 	"role.integration": () => "integration branch",
@@ -372,6 +455,8 @@ const en = {
 	"head.unknown": () => "current branch",
 	"denyDeleteOrForce.why": (v) => `Protected branch "${v.branch}" may not be deleted or force-pushed`,
 	"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.",
 	"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?)",
@@ -393,8 +478,6 @@ const en = {
 	"prMergeArchive.next": () => "Let the user do the archive merge in their terminal or UI.",
 	"prMergeUnknown.why": () => "Cannot confirm the PR/MR target branch",
 	"prMergeUnknown.next": () => "Retry once gh/glab is available, or let the user handle it.",
-	"prMergeHead.why": () => "Cannot confirm the PR/MR target, and the head is not a feature branch",
-	"prMergeHead.next": () => "Confirm the platform CLI is available, or let the user handle it.",
 	"next.integration": (v) => `Integration branch (${v.branch}) is updated via PR/MR from a feature branch: push the feature first, then \`gh pr create --base ${v.branch}\` / \`glab mr create --target-branch ${v.branch}\`.`,
 	"next.preview": (v) => `Preview branch (${v.branch}) only accepts PR/MRs: open a PR/MR into it from a feature/release branch (content of ${v.base} etc. first goes into a feature release branch).`,
 	"next.production": (v) => `Production branch (${v.branch}) is PR/MR-only, and you click the merge yourself.`,
@@ -407,6 +490,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})`,
@@ -417,16 +501,22 @@ const en = {
 	"cli.statusLocalBranches": () => "Local branches (by role):",
 	"cli.auditEmpty": () => "  No audit entries yet",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check internal error, allowed through: ${v.msg}`,
+	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] guard disabled: invalid config: ${v.err}`,
+	"guardStrictConfigBroken.why": () => "Guard config is invalid while strict mode is enabled",
+	"guardStrictConfigBroken.next": () => "Fix gitflow-guard.config.json (or remove \"strict\": true) before retrying.",
+	"guardStrictInternalError.why": (v) => `Guard internal error while strict mode is enabled: ${v.msg}`,
+	"guardStrictInternalError.next": () => "Fix or remove \"strict\": true in gitflow-guard.config.json.",
 	"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.`
 };
@@ -440,6 +530,8 @@ const zh = {
 	"head.unknown": () => "当前分支",
 	"denyDeleteOrForce.why": (v) => `受保护分支「${v.branch}」禁止删除或强推`,
 	"denyDeleteOrForce.next": () => "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理",
+	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref)`,
+	"refUpdateProtected.next": () => "请通过 PR/MR 更新受保护分支; 受保护分支由用户亲手管理",
 	"pushAll.why": () => "--all/--mirror 推送会包含受保护分支",
 	"pushAll.next": () => "请逐分支推送并显式指定 refspec",
 	"pushDetached.why": () => "无法确定推送目标分支(可能处于 detached HEAD)",
@@ -461,8 +553,6 @@ const zh = {
 	"prMergeArchive.next": () => "请让用户在自己终端或 UI 完成归档合并",
 	"prMergeUnknown.why": () => "无法确认 PR/MR 的目标分支",
 	"prMergeUnknown.next": () => "请确认 gh/glab 可用后重试, 或让用户亲手处理",
-	"prMergeHead.why": () => "无法确认 PR/MR 目标, 且 head 不是 feature 分支",
-	"prMergeHead.next": () => "请确认平台 CLI 可用, 或让用户亲手处理",
 	"next.integration": (v) => `集成分支(${v.branch})由 PR/MR 合入 feature: 先推 feature 分支, 再 gh pr create --base ${v.branch} / glab mr create --target-branch ${v.branch}`,
 	"next.preview": (v) => `预览分支(${v.branch})只收 PR/MR: 从 feature/发布分支创建指向它的 PR/MR(${v.base} 等集成分支内容先进 feature 发布分支)`,
 	"next.production": (v) => `生产分支(${v.branch})只能 PR/MR, 且合并由你亲手点击`,
@@ -475,6 +565,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})`,
@@ -485,27 +576,46 @@ const zh = {
 	"cli.statusLocalBranches": () => "本地分支(按角色):",
 	"cli.auditEmpty": () => "  暂无审计记录",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check 内部错误, 已放行: ${v.msg}`,
+	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] 守卫未启用: 配置无效: ${v.err}`,
+	"guardStrictConfigBroken.why": () => "守卫配置无效, 且已启用 strict 模式",
+	"guardStrictConfigBroken.next": () => "请先修复 gitflow-guard.config.json(或移除 \"strict\": true)后重试",
+	"guardStrictInternalError.why": (v) => `守卫内部错误, 且已启用 strict 模式: ${v.msg}`,
+	"guardStrictInternalError.next": () => "请修复 gitflow-guard.config.json 或移除 \"strict\": true",
 	"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;
@@ -516,9 +626,177 @@ 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, 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 = [];
+	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, "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,
+		warnings,
+		...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: [],
+			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
@@ -564,6 +842,7 @@ function decide(classified, facts, config, t = defaultT) {
 		case "pr-create": return decidePrCreate(classified, facts, config, t);
 		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 "guard-cli": return { kind: "allow" };
 		case "checkout": return { kind: "allow" };
 		default: return { kind: "allow" };
@@ -611,18 +890,14 @@ function decidePrCreate(c, facts, config, t) {
 }
 function decidePrMerge(c, facts, config, t) {
 	const resolved = facts.resolvePrTarget?.(c.pr) ?? null;
-	const role = resolved?.role ?? null;
-	const head = resolved?.head ?? facts.currentBranch;
+	if (!resolved) return deny(t("prMergeUnknown.why"), t("prMergeUnknown.next"));
+	const role = resolved.role;
 	if (role === "production") {
 		if (config.branches.production?.mergeBy === "user") return deny(t("prMergeProduction.why"), t("prMergeProduction.next"));
 		return { kind: "allow" };
 	}
 	if (role === "archive") return deny(t("prMergeArchive.why"), t("prMergeArchive.next"));
-	if (role === "integration" || role === "preview") return { kind: "allow" };
-	if (role === "feature" || role === "other") return { kind: "allow" };
-	if (head == null) return deny(t("prMergeUnknown.why"), t("prMergeUnknown.next"));
-	if (roleOfBranch(head, config) === "feature") return { kind: "allow" };
-	return deny(t("prMergeHead.why"), t("prMergeHead.next"));
+	return { kind: "allow" };
 }
 /** 受保护分支被拦后的下一步引导 */
 function branchNext(branch, config, t) {
@@ -780,7 +1055,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 = {
@@ -883,10 +1158,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, makeT as f, classify as h, formatDeny as i, gitRunner as l, resolveLocale as m, apply as n, stateDir as o, registerLocale 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.10",
+  "version": "0.0.12",
   "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"