agents-gitflow-guard 0.0.9 → 0.0.11

package/README.md

@@ -36,12 +36,16 @@ You define your own branches —
 
 ## Quick Start — 30 seconds to a guarded repo
 
-**Step 1 — install**, one command, then restart DSH (plugins load at process startup):
+**Step 1 — install**, then restart DSH (plugins load at process startup):
 
 ```bash
+# 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
 ```
 
+> **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
@@ -253,6 +257,7 @@ archive (optional; you archive after release)
     "archive":     ["main"]                                      // optional
   },
   "locale": "en",                      // optional: message language ('en' default, or 'zh')
+  "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
 }
 ```
@@ -263,6 +268,7 @@ archive (optional; you archive after release)
 - Each branch entry is an exact name or a regex (auto-detected).
 - **Language**: messages are English by default; add `"locale": "zh"` for Chinese.
 - **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.
 
 ---
 
@@ -295,7 +301,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
+dsh plugin --profile web add agents-gitflow-guard@0.0.9    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -387,7 +393,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.
 
 ---
 
@@ -399,7 +407,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.
 
 ---
 

package/README.zh.md

@@ -35,12 +35,16 @@
 
 ## 快速开始——30 秒用上
 
-**第 1 步——安装**,一条命令,然后重启 DSH(插件在进程启动时加载):
+**第 1 步——安装**,然后重启 DSH(插件在进程启动时加载):
 
 ```bash
+# 安装最新版
 dsh plugin --profile web add agents-gitflow-guard
+# ...或锁定已知良好版本(推荐; 同时绕开 registry 陈旧缓存)
+dsh plugin --profile web add agents-gitflow-guard@0.0.9
 ```
 
+> **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
 **第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
 
 ```jsonc
@@ -250,6 +254,7 @@ archive(可选, 发布后你亲手归档)
     "archive":     ["main"]                                      // 可选
   },
   "locale": "en",                      // 可选: 文案语言('en' 默认, 或 'zh')
+  "strict": false,                     // 可选: fail-closed —— 配置异常/内部错误改为拦截, 而非告警放行
   "ci": { "enabled": true }            // 可选: gh pr checks 作参考日志
 }
 ```
@@ -260,6 +265,7 @@ archive(可选, 发布后你亲手归档)
 - 每条分支条目是精确名或正则(自动识别)。
 - **文案语言**:默认英文;加 `"locale": "zh"` 切中文。
 - **校验**:`integration` 必填;角色条目重叠会被拒;非法正则会报错。**任何错误都会让该项目的插件禁用并上报**(而不是用半吊子配置)。
+- **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。文件不存在或显式 `enabled: false` 两种模式下都保持静默。
 
 ---
 
@@ -292,7 +298,7 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 **从 npm registry**——标准路径,已在[快速开始](#快速开始30-秒用上)覆盖:
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard
+dsh plugin --profile web add agents-gitflow-guard@0.0.9    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -384,7 +390,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 …')"`);任意深度的引号/编码变换天然只能尽力而为。真正不可绕过的边界在你托管服务的分支保护设置。两边都用——把本守卫当作即时反馈与审计留痕,而不是安全边界。
 
 ---
 
@@ -396,7 +404,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、自托管或离线环境里行为一致。
 
 ---
 

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 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 { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts
@@ -205,35 +205,52 @@ 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;
 	try {
-		const raw = flags.command != null ? "" : await readStdin();
+		raw = flags.command != null ? "" : await readStdin();
 		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 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(platformFlag === "auto" ? detectPlatform(raw) : platformFlag, 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) {
-			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;
-		}
+		if (result.outcome === "deny" && result.reason) return emitDeny(hookPlatform, 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"));
+		}
 		process.stderr.write(`${makeT("en")("cli.checkInternalError", { msg: e.message })}\n`);
 		return 0;
 	}

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";
+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 };

package/lib/{src-CeEqUVQP.mjs → src-DTg5WMog.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 [{
@@ -268,7 +495,7 @@ function normalizeRole(raw, defaultUpdate, defaultMergeBy) {
 		errors
 	};
 }
-/** 合并默认值并校验; 任何校验错误都会导致未启用 */
+/** 合并默认值并校验; 任何校验错误都会导致未启用(strict 位仍从原文提取, 供 fail-closed 判定) */
 function mergeConfig(raw) {
 	const errors = [];
 	if (typeof raw !== "object" || raw === null) return {
@@ -276,6 +503,8 @@ function mergeConfig(raw) {
 		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 },
@@ -312,10 +541,12 @@ function mergeConfig(raw) {
 	}
 	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
+		errors,
+		...strict !== void 0 ? { strict } : {}
 	};
 }
 /** 配置校验: 角色分支重叠 / 正则合法等 */
@@ -346,9 +577,9 @@ function validateConfig(config) {
 }
 /** 从项目根加载配置; 无文件 = 未启用(opt-in) */
 async function loadConfig(repoRoot) {
+	let text;
 	try {
-		const text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
-		return mergeConfig(JSON.parse(text));
+		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
 	} catch (e) {
 		if (e.code === "ENOENT") return {
 			config: null,
@@ -359,6 +590,18 @@ async function loadConfig(repoRoot) {
 			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
@@ -372,6 +615,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 +638,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.`,
@@ -417,6 +660,11 @@ 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:
@@ -440,6 +688,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 +711,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, 且合并由你亲手点击`,
@@ -485,6 +733,11 @@ 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
 
 用法:
@@ -564,6 +817,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 +865,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "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",