agents-gitflow-guard 0.0.12 → 0.0.14

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.12
+dsh plugin --profile web add agents-gitflow-guard@0.0.14
 ```
 
 > **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
@@ -131,7 +132,7 @@ Nobody has to remember the rules — the rules are enforced.
 - **Role-driven, fully configurable**: `integration` is the only required role; `preview` / `production` / `archive` are optional arrays of branch names or regexes, each with its own update rules (`pr` / `flexible`, `mergeBy`).
 - **Merge-by-user where it matters**: production & archive merges stay in your hands — the plugin blocks the agent from clicking merge, so your action *is* the confirmation.
 - **Works with any naming**: branch names are mapped by your config, never hard-coded (see [Configuration](#configuration-reference)).
-- **Fully audited**: every deny is written to `.git/gitflow-guard/audit.jsonl` — inside `.git`, never committed.
+- **Fully audited**: every deny is appended to an audit log under your user state directory (`~/.local/state/gitflow-guard/`, `%LOCALAPPDATA%\gitflow-guard` on Windows) — outside the repository, never committed, and outside the agent's writable sandbox.
 - **Platform-agnostic core**: pure local git; optionally consults `gh` (GitHub) or `glab` (GitLab) for PR/MR target resolution, and works fine without them.
 
 ---
@@ -167,7 +168,7 @@ Why this matters: branch protection answers *"can this push happen at all?"*; th
 
 1. An agent calls a shell tool (`pwsh` / `bash`) with a git command.
 2. The plugin classifies the command, resolves the branch roles from `gitflow-guard.config.json`, and applies the gate matrix.
-3. Violation → the tool call is **denied before it runs**, with a reason and the next step. Allowed → the command proceeds; every deny is audited to `.git/gitflow-guard/audit.jsonl`.
+3. Violation → the tool call is **denied before it runs**, with a reason and the next step. Allowed → the command proceeds; every deny is audited to the user-level log (`~/.local/state/gitflow-guard/repos/<repo>-<hash>/audit.jsonl`).
 
 No chat-confirmation or permit store: sensitive merges (production / archive) are simply **user-only** — an agent may prepare the PR/MR, but the merge click stays yours.
 
@@ -268,6 +269,14 @@ archive (optional; you archive after release)
 - 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.
@@ -293,17 +302,17 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 ## Where the human stays in control
 
 - **Production merge** and **archive** are user-only by default: an agent may help prepare the PR/MR, but **you click the merge button** — that click *is* the confirmation. There is no separate permit store to outsource that decision.
-- Every deny is written to `.git/gitflow-guard/audit.jsonl` for review (`gitflow-guard audit`).
+- Every deny is appended to the user-level audit log for review (`gitflow-guard audit`).
 
 ---
 ## 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.12    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.14    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -403,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.
 
 ---
 
@@ -462,7 +471,7 @@ If it saves your team from a shortcut gone wrong, the coffee button at the top o
 ## Roadmap
 
 - **i18n — localized block messages** ✅ (0.0.3): English by default, `"locale": "zh"` for Chinese.
-- **v2 — audit sync**: sync `.git/gitflow-guard/audit.jsonl` across machines (audit is local-only today).
+- **v2 — audit sync**: sync the user-level audit log across machines (audit is local-only today).
 - **v2 — more pre-built templates**: ready-made config templates for common flows (solo `develop`, multi-env enterprise) as community-contributed presets.
 - **v2 — CI hard-gating research**: whether `pr checks` could become a real gate without hurting the platform-agnostic core.
 
@@ -482,7 +491,7 @@ 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 + zh-locale regression + Claude Code / Codex / OpenCode / Antigravity hook wiring
@@ -490,7 +499,7 @@ npm run verify:matrix # continuous cross-agent regression: DSH logic + zh-locale
 
 **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.)
 
 ---
 
@@ -498,4 +507,4 @@ npm run verify:matrix # continuous cross-agent regression: DSH logic + zh-locale
 
 [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.12
+dsh plugin --profile web add agents-gitflow-guard@0.0.14
 ```
 
 > **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
+
 **第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
 
 ```jsonc
@@ -128,7 +129,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 - **角色驱动、完全可配**:`integration` 是唯一必填;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个角色独立 `update`(`pr` / `flexible`)与 `mergeBy`。
 - **在关键处保留人的操作权**:生产与归档合并始终在你手上——插件阻止 agent 点击合并,于是你的动作*就是*确认。
 - **任何命名都行**:分支名全由配置映射,绝无硬编码(见[配置参考](#配置参考))。
-- **全程审计**:每次拦截都写入 `.git/gitflow-guard/audit.jsonl`——在 `.git` 内,绝不进版本库。
+- **全程审计**:每次拦截都追加到用户级状态目录(macOS/Linux `~/.local/state/gitflow-guard/`,Windows `%LOCALAPPDATA%\gitflow-guard`)下的审计日志——在仓库外、绝不进版本库,且位于 agent 可写沙箱之外。
 - **平台无关核心**:纯本地 git;可选调用 `gh`(GitHub)或 `glab`(GitLab)做 PR/MR 目标解析,没有它们照样工作。
 
 ---
@@ -164,7 +165,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 1. agent 调用 shell 工具(`pwsh`/`bash`)执行一条 git 命令。
 2. 插件分类该命令,从 `gitflow-guard.config.json` 解析分支角色,套用门禁矩阵。
-3. 违规 → 工具调用在**运行前被拒绝**,附原因和下一步;放行 → 命令照常执行,每次拦截都写入 `.git/gitflow-guard/audit.jsonl`。
+3. 违规 → 工具调用在**运行前被拒绝**,附原因和下一步;放行 → 命令照常执行,每次拦截都写入用户级日志(`~/.local/state/gitflow-guard/repos/<repo>-<hash>/audit.jsonl`)。
 
 没有聊天确认、也没有特许库:敏感合并(生产/归档)就是**仅用户**——agent 可以帮你准备 PR/MR,但点合并的始终是你。
 
@@ -265,6 +266,13 @@ archive(可选, 发布后你亲手归档)
 - 每条分支条目是精确名或正则(自动识别)。**正则安全**:分支正则由项目作者提供并按原样编译——`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` 两种模式下都保持静默。
@@ -279,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`) | 🚫 拦——逐段模拟分支切换,无法绕序 |
 
@@ -290,17 +298,17 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 ## 人保持控制权的地方
 
 - **生产合并与归档**默认仅用户:agent 可以帮你准备 PR/MR,但**合并按钮由你点**——那个点击*就是*确认。没有独立特许库能把这决定外包出去。
-- 每次拦截都写入 `.git/gitflow-guard/audit.jsonl` 供查阅(`gitflow-guard audit`)。
+- 每次拦截都追加到用户级审计日志供查阅(`gitflow-guard audit`)。
 
 ---
 ## 安装详解
 
-**前置**:一个可用的 [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.12    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.14    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -400,7 +408,7 @@ hooks:
 
 ### 为什么 agent 不能自己合并进生产/归档?
 
-因为门禁把那些动作判定为**仅用户**。agent 可以创建 PR/MR,但对生产的*合并*、对归档的*建 PR 与合并*插件一律拒绝。唯一路径是**你**点合并——不存在 agent 能用来给自己授权的特许、令牌或聊天消息。
+因为门禁把那些动作判定为**仅用户**。插件对生产的*合并*、归档的*合并*一律拦截——*建 PR/MR 允许*,agent 仍可替你起草 develop→main 归档 PR。但合并本身只有一条路径:**你**亲手点合并——不存在 agent 能用来给自己授权的特许、令牌或聊天消息。
 
 ---
 
@@ -448,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** | 工具管线中拦截发生的钩子——在命令运行之前 |
@@ -459,7 +467,7 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 ## 路线图
 
 - **i18n——拦截文案本地化** ✅(0.0.3):默认英文,`"locale": "zh"` 切中文。
-- **v2——审计同步**:跨机器同步 `.git/gitflow-guard/audit.jsonl`(现仅本地)。
+- **v2——审计同步**:跨机器同步用户级审计日志(现仅本地)。
 - **v2——更多预制模板**:常用流程(solo `develop`、多环境企业)的现成配置模板,由社区贡献。
 - **v2——CI 硬门槛研究**:`pr checks` 能否在不伤平台无关核心的前提下变成真实门槛。
 
@@ -479,7 +487,7 @@ 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 编码
@@ -487,10 +495,12 @@ npm run verify:matrix # 连续复测矩阵: DSH 逻辑 + zh 文案回归 + Claud
 
 **铁律**:任何逻辑改动必须 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 清单,见该节例外说明。)
+
 ---
 
 ## 许可证
 
 [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 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 { _ as classify, c as currentBranch, d as loadConfig, f as roleMatches, g as resolveLocale, i as formatDeny, l as findRepoRoot, m as makeT, o as stateDir, r as evaluateCommand, u as gitRunner } from "./src-C1CZM7Q4.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts

package/lib/index.d.mts

@@ -11,6 +11,7 @@ type I18nVars = Record<string, string>;
 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 一律回退英文。
@@ -52,6 +53,17 @@ interface AuditEntry {
   role?: string;
   reason?: string;
 }
+/**
+ * 用户级运行时状态根目录(仓库外): macOS/Linux 走 XDG state, Windows 走 %LOCALAPPDATA%。
+ * GITFLOW_GUARD_STATE_ROOT 显式覆盖所有平台默认值(测试/特殊部署用)。
+ */
+declare function userStateRoot(): string;
+/**
+ * 仓库运行时状态目录(审计流水等), 键为「仓库名-真实路径哈希」。
+ * 刻意放在仓库外、且在 agent 文件沙箱(workspace-write)可写区之外:
+ * 凡 agent 可写之处的状态都可能被 agent 伪造而自我授权, 存仓库外才堵住这条路;
+ * 附带收益: 重克隆/移动 .git 不丢历史。
+ */
 declare function stateDir(repoRoot: string): string;
 /** 审计留痕; 失败不阻断门禁 */
 declare function appendAudit(repoRoot: string, entry: AuditEntry): Promise<void>;
@@ -60,4 +72,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, type Dict, EvaluateOptions, EvaluateResult, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };
+export { AuditEntry, type Dict, EvaluateOptions, EvaluateResult, MESSAGE_KEYS, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/index.mjs

@@ -1,2 +1,2 @@
-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 };
+import { a as name, h as registerLocale, i as formatDeny, n as apply, o as stateDir, p as MESSAGE_KEYS, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-C1CZM7Q4.mjs";
+export { MESSAGE_KEYS, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

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

@@ -1,5 +1,8 @@
 import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
 import { execFile } from "node:child_process";
 //#region src/classify.ts
 /** 拆分命令为多段(&& / || / | / 分号 / 换行), 每段独立分类; 引号内的分隔符不算 */
@@ -174,10 +177,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 +411,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" }];
 }
@@ -457,6 +528,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?)",
@@ -532,6 +605,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)",
@@ -656,7 +731,7 @@ function roleMatches(branch, role) {
 	return role.branches.some((spec) => matchBranchSpec(branch, spec));
 }
 /** 规范化用户输入的某个角色: 数组 或 {branches:[...], update?, mergeBy?} */
-function normalizeRole(raw, defaultUpdate, defaultMergeBy) {
+function normalizeRole(raw, roleName, defaultUpdate, defaultMergeBy) {
 	const errors = [];
 	let arr;
 	let update = void 0;
@@ -673,6 +748,11 @@ function normalizeRole(raw, defaultUpdate, defaultMergeBy) {
 	};
 	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;
@@ -711,22 +791,22 @@ function mergeConfig(raw) {
 	} 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");
+		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, "pr", "anyone");
+		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, "pr", "user");
+		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, "pr", "user");
+		const { role, errors: e } = normalizeRole(b.archive, "archive", "pr", "user");
 		config.branches.archive = role;
 		errors.push(...e);
 	}
@@ -741,7 +821,7 @@ function mergeConfig(raw) {
 		...strict !== void 0 ? { strict } : {}
 	};
 }
-/** 配置校验: 角色分支重叠 / 正则合法等 */
+/** 配置校验: 角色分支重叠等(角色条目正则合法性已在 normalizeRole 预编译报错) */
 function validateConfig(config) {
 	const errors = [];
 	if (config.branches.integration.branches.length === 0) errors.push("branches.integration.branches is required");
@@ -843,6 +923,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" };
@@ -1034,8 +1115,38 @@ function resolvePrTarget(info, config) {
 //#endregion
 //#region src/index.ts
 const name = "gitflow-guard";
+/**
+* 用户级运行时状态根目录(仓库外): macOS/Linux 走 XDG state, Windows 走 %LOCALAPPDATA%。
+* GITFLOW_GUARD_STATE_ROOT 显式覆盖所有平台默认值(测试/特殊部署用)。
+*/
+function userStateRoot() {
+	const override = process.env.GITFLOW_GUARD_STATE_ROOT?.trim();
+	if (override) return override;
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA?.trim() || join(homedir(), "AppData", "Local");
+		return join(local, "gitflow-guard");
+	}
+	const xdg = process.env.XDG_STATE_HOME?.trim();
+	return join(xdg || join(homedir(), ".local", "state"), "gitflow-guard");
+}
+function canonicalRepoRoot(repoRoot) {
+	try {
+		return realpathSync(repoRoot);
+	} catch {
+		return repoRoot;
+	}
+}
+/**
+* 仓库运行时状态目录(审计流水等), 键为「仓库名-真实路径哈希」。
+* 刻意放在仓库外、且在 agent 文件沙箱(workspace-write)可写区之外:
+* 凡 agent 可写之处的状态都可能被 agent 伪造而自我授权, 存仓库外才堵住这条路;
+* 附带收益: 重克隆/移动 .git 不丢历史。
+*/
 function stateDir(repoRoot) {
-	return join(repoRoot, ".git", "gitflow-guard");
+	const real = canonicalRepoRoot(repoRoot);
+	const hash = createHash("sha256").update(real).digest("hex").slice(0, 12);
+	const name = basename(real).replace(/[^\w.-]+/g, "-") || "repo";
+	return join(userStateRoot(), "repos", `${name}-${hash}`);
 }
 /** 审计留痕; 失败不阻断门禁 */
 async function appendAudit(repoRoot, entry) {
@@ -1164,4 +1275,4 @@ function apply(ctx, pluginConfig = {}) {
 	});
 }
 //#endregion
-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 };
+export { classify as _, name as a, currentBranch as c, loadConfig as d, roleMatches as f, resolveLocale as g, registerLocale as h, formatDeny as i, findRepoRoot as l, makeT as m, apply as n, stateDir as o, MESSAGE_KEYS as p, evaluateCommand as r, userStateRoot as s, appendAudit as t, gitRunner as u };

package/package.json

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

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