edit

zichun
1 parent cc94a5f4
Showing 23 changed files with 198 additions and 88 deletions
.claude-plugin/plugin.json
README.md
skills/coding/erp-feature-brainstorm/SKILL.md
skills/coding/erp-feature-plan/SKILL.md
skills/coding/erp-feature-review/SKILL.md
skills/coding/erp-feature-review/templates/feature-review-template.md
skills/coding/erp-feature-tdd/SKILL.md
skills/coding/erp-feature-verify/SKILL.md
skills/coding/erp-local-test-gate/SKILL.md
skills/coding/erp-module-report/SKILL.md
skills/coding/erp-mr-create/SKILL.md
skills/coding/erp-mr-create/templates/mr-description-template.md
skills/crosscut/erp-coding-start/SKILL.md
skills/crosscut/erp-plan-start/SKILL.md
skills/crosscut/erp-red-flag-check/SKILL.md
skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md
skills/plan/erp-db-design-gen/SKILL.md
skills/plan/erp-db-init/SKILL.md
skills/plan/erp-downstream-gen/SKILL.md
skills/plan/erp-project-init/templates/CLAUDE-template.md
@@ -2,5 +2,5 @@
   "name": "erp-workflow",
   "description": "ERP 项目全流程框架：阶段 A 计划（一次性） + 阶段 B 编码（模块循环 + 功能循环），含完整 skill 流水线 + 守门 hook + 软规则留痕。专为后端 Spring Boot + 前端 React + MySQL 8 的 ERP/管理类系统设计。",
   "version": "0.1.0",
-  "skills": ["./skills/plan", "./skills/coding", "./skills/crosscut"]
+  "skills": ["./skills/plan", "./skills/coding", "./skills/crosscut", "./skills/internal"]
 }
@@ -164,7 +164,7 @@ erp-workflow-plugin/
 |---|---|---|
 | `erp-plan-start` | **A 阶段入口**。读取 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:erp-plan-start` |
 | `erp-coding-start` | **B 阶段入口**。先验证 Plan 已完成；**按 `docs/02 § 二` REQ 序扫描**，对每个 REQ 所属模块查询 `MR: 字段 + glab mr view state`：`merged` 跳过；`—`/opened/closed/查不到 选为当前模块。派发前 `git checkout main + git pull --ff-only` 同步远程 base，然后调用 `erp-module-start` | **用户手动**运行 `/erp-workflow:erp-coding-start` |
-| `erp-red-flag-check` | 检查 CLAUDE.md 的 6 项红旗清单；命中则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
+| `erp-red-flag-check` | 检查 CLAUDE.md 的 3 项红旗清单；命中则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
 | `erp-cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根补「原因 / 影响评估」 | 用户看到 hook 提示后调用；`erp-module-start` 初始化日志文件时也会用其模板 |
 ## Templates 清单（38 份）
@@ -11,7 +11,7 @@ allowed-tools: Read Write Skill Bash(mysql *)
 ## 说明
-针对一个 REQ-XXX-NNN，委托 `superpowers:brainstorming` 进行头脑风暴，再把输出填入标准规格模板，产出单页功能规格。
+针对一个 REQ-XXX-NNN，委托本插件的 `superpower-brainstorming`（superpowers:brainstorming 的本地 fork，已剥掉 approval gates）进行头脑风暴，再把输出填入标准规格模板，产出单页功能规格。
 ## 执行步骤
@@ -20,7 +20,7 @@ allowed-tools: Read Write Skill Bash(mysql *)
    - 当前 REQ-XXX-NNN（从对话中获取，或 `docs/08` 当前模块下一个未完成的 REQ）。
    - REQ 卡片：`docs/01-需求清单/<module>.md` 中对应的 REQ-XXX-NNN 节。
    - 相关数据表（从 `docs/03` 或实时 mysql 命令行查询）。
-3. 委托 `superpowers:brainstorming`，以 REQ 卡片 + schema 引用作为上下文。
+3. 委托本插件 `superpower-brainstorming`，以 REQ 卡片 + schema 引用作为上下文；把步骤 4 推导出的落盘路径作为 caller-provided path 传入。
 4. 推导路径：`docs/superpowers/specs/$(date +%F)-<REQ-id>.md`。如已存在，征求用户确认后覆盖。
 5. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md`，从头脑风暴输出填充槽位：
    - `goal`、`input`、`output`、`rules`、`constraints`、`schema_refs`、`api_refs`、`acceptance`
@@ -35,5 +35,5 @@ allowed-tools: Read Write Skill Bash(mysql *)
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md`
-- 委托：`superpowers:brainstorming`
+- 委托：`superpower-brainstorming`（本插件 `skills/internal/superpower-brainstorming/`，superpowers:brainstorming 的无门 fork）
 - 守门：`erp-red-flag-check`
@@ -16,7 +16,7 @@ allowed-tools: Read Write Grep Skill
    - 当前 REQ-XXX-NNN 及其规格文件 `docs/superpowers/specs/YYYY-MM-DD-<REQ>.md`（规格不存在则报错）。
    - 相关代码指针（已有的待修改文件，通过 Grep 发现）。
    - `docs/04-技术规范.md` 和 `docs/09-项目目录结构.md`（编码规范 + 目录规范）。
-3. 委托 `superpowers:writing-plans`，以规格 + 代码指针 + 规范作为上下文。
+3. 委托本插件 `superpower-writing-plans`（superpowers:writing-plans 的本地 fork，已剥掉"Which approach?"执行交接门），以规格 + 代码指针 + 规范作为上下文；把步骤 4 推导出的落盘路径作为 caller-provided path 传入。
 4. 推导路径：`docs/superpowers/plans/$(date +%F)-<REQ-id>.md`。
 5. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md`，填充 `files[]`、`tasks[]`、`commits[]`。
 6. 强制要求：每个任务有失败测试标识、实现路径和完成标准。
@@ -30,5 +30,5 @@ allowed-tools: Read Write Grep Skill
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md`
-- 委托：`superpowers:writing-plans`
+- 委托：`superpower-writing-plans`（本插件 `skills/internal/superpower-writing-plans/`，superpowers:writing-plans 的无门 fork）
 - 守门：`erp-red-flag-check`
@@ -11,7 +11,7 @@ allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *)
 ## 执行步骤
-1. 委托 `superpowers:code-reviewer`，以该 REQ 的 diff（`git diff <feature-start>..HEAD`）和规格作为输入。
+1. 通过 `Agent(subagent_type=superpower-code-reviewer)` 调用本插件 code-reviewer agent（superpowers:code-reviewer 的本地 fork），以该 REQ 的 diff（`git diff <feature-start>..HEAD`）和规格作为输入。
 2. 推导路径：`docs/superpowers/reviews/$(date +%F)-<REQ-id>.md`。
 3. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md`，填充 `round`、`verdict`、`must_fix[]`、`nice_to_have[]`、`gaps`。verdict 必须是 `approve` 或 `request-changes`。
 4. 写入报告。
@@ -36,6 +36,6 @@ allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *)
 - `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md`
 - Fix commit 格式与 `erp-feature-tdd` 的 `commit-message-template.md` 对齐（`fix(<scope>): <subject> <req_id>`）
-- 委托：`superpowers:code-reviewer`
+- 委托：`superpower-code-reviewer`（本插件 `agents/superpower-code-reviewer.md`，superpowers:code-reviewer 的本地 fork）
 - 上游：`erp-feature-verify`
 - 下游：`erp-module-start`（approve）或 `erp-feature-verify`（request-changes）
@@ -2,7 +2,7 @@
 req_id: {{req_id}}
 date: {{date}}
 round: {{round}}
-reviewer: superpowers:code-reviewer
+reviewer: superpower-code-reviewer
 ---
 # Review: {{req_id}} — round {{round}}
@@ -23,7 +23,7 @@ allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *)
    b. **派发子会话**（通过 `Agent`，general-purpose）运行测试并确认失败；子会话只返回 `{command, exit_code, failing_assertion}`。主会话**不直接**运行测试。
    c. 在 `impl_file` 处实现最小代码使测试通过。
    d. **再次派发子会话**运行测试并确认通过。
-   e. 持续失败（同一测试 >10 次修复尝试）→ 调用 `erp-red-flag-check`（红旗 #4）。
+   e. 持续失败（同一测试 >10 次修复尝试）→ 调用 `erp-red-flag-check`（红旗 #1）。
    f. 暂存变更并使用 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 提交；`scope` 匹配任务的模块，`subject` ≤50 字符，`req_id` 必填。
 5. 所有任务完成后 → 交接给 `erp-feature-verify`。
@@ -41,5 +41,5 @@ allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *)
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md`
-- 委托：`superpowers:test-driven-development`
+- 原则参考：`superpowers:test-driven-development`（本插件未镜像；仅作为 TDD 原则手册参考，不做运行时 invoke — 本 skill 已把"子会话跑测试 + REQ tag commit"流程直接写死）
 - 守门：`erp-red-flag-check`
@@ -37,4 +37,4 @@ allowed-tools: Skill Read Write Agent
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/feature-verify-evidence-template.md`
-- 委托：`superpowers:verification-before-completion`
+- 原则参考：`superpowers:verification-before-completion`（本插件未镜像；仅作为"证据先于断言"原则参考，不做运行时 invoke — 本 skill 已把子会话派发 + 模板渲染证据流程直接写死）
@@ -25,7 +25,7 @@ allowed-tools: Read Write Skill Agent Bash(git add *) Bash(git commit *)
 3. 写入 `docs/superpowers/module-reports/<module_id>-test-gate.md`。
-3b. **commit evidence 到 module 分支**（确保 test-gate.md 随 MR 合并进 main，审计可追溯）：
+3b. **commit evidence 到 module 分支**（确保 test-gate.md 随 MR 合并进默认分支，审计可追溯）：
    ```bash
    git add docs/superpowers/module-reports/<module_id>-test-gate.md
@@ -57,7 +57,7 @@ allowed-tools: Read Write Skill Agent Bash(git add *) Bash(git commit *)
          （module-start 把该 REQ 视为未完成，重走 brainstorm→...→review 循环修复）
     ③ 环境/依赖问题（DB 连不上、外部 API 失败、证书失效）
-       → 命中红旗 #6（外部接口不可达）
+       → 命中红旗 #3（外部接口不可达）
        → 调用 Skill(erp-red-flag-check) 追加 Blocker 到本模块任一 plan 文件
        → 修复环境后重新运行 /erp-workflow:erp-coding-start
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -31,7 +31,7 @@ allowed-tools: Read Write Glob Grep Skill Bash(git diff *) Bash(git log *) Bash(
    - § ⑧ 必须列举所有偏离规格之处；如果没有，明确写"无偏离"。
 5. 写入 `docs/superpowers/module-reports/$(date +%F)-<module_id>.md`。
-5b. **commit 模块报告 + cross-module 日志到 module 分支**（确保审计证据随 MR 合并进 main；erp-mr-create 的 worktree clean 前置条件依赖此步）：
+5b. **commit 模块报告 + cross-module 日志到 module 分支**（确保审计证据随 MR 合并进默认分支；erp-mr-create 的 worktree clean 前置条件依赖此步）：
    ```bash
    git add docs/superpowers/module-reports/$(date +%F)-<module_id>.md
@@ -2,7 +2,7 @@
 name: erp-mr-create
 description: 模块报告完成后，验证当前分支为 module-<id> 且 worktree 干净，push 推代码和所有 evidence，创建 GitLab MR（报告嵌入描述），把 MR URL 追加到模块报告 § ⑫ 并 commit，把 MR iid 回写到 docs/08 该模块 `MR:` 字段并 commit，再次 push 同步。完成信号由 MR merged state 判定。停下等待人工审核。
 user-invocable: false
-allowed-tools: Read Write Edit Skill Bash(git *) Bash(glab *) Bash(sed *) Bash(awk *) Bash(cat *) Bash(echo *) Bash(mkdir -p .tmp) Bash(mv .tmp/*) Bash(rm -f .tmp/*)
+allowed-tools: Read Write Edit Skill Bash(git *) Bash(glab *) Bash(jq *) Bash(sed *) Bash(awk *) Bash(cat *) Bash(echo *) Bash(mkdir -p .tmp) Bash(mv .tmp/*) Bash(rm -f .tmp/*)
 ---
 **所有输出必须使用中文。**
@@ -81,7 +81,20 @@ mv .tmp/mr-desc.final &quot;$DESC_FILE&quot;
 关键：**模块报告内容只经 awk 管道流过**，从不进入 LLM 上下文。
-### 步骤 6：创建 MR
+### 步骤 5.5：幂等守门——检查 source branch 是否已有 opened MR
+
+防止部分失败后重试创建重复 MR：
+
+```bash
+EXISTING_JSON=$(glab mr list --source-branch "<current_branch>" --state opened -F json 2>/dev/null)
+EXISTING_IID=$(echo "$EXISTING_JSON" | jq -r '.[0].iid // empty')
+EXISTING_URL=$(echo "$EXISTING_JSON" | jq -r '.[0].web_url // empty')
+```
+
+- `EXISTING_IID` 非空 → 打印 `[erp-mr-create] 检测到已有 opened MR: !${EXISTING_IID}`，**跳过步骤 6**，直接用 `EXISTING_IID` / `EXISTING_URL` 进入步骤 7。
+- `EXISTING_IID` 为空 → 正常走步骤 6 创建新 MR。
+
+### 步骤 6：创建 MR（仅当 5.5 未命中时）
 ```bash
 TITLE_FILE=.tmp/mr-title.txt
@@ -90,20 +103,23 @@ glab mr create --title &quot;$(cat &quot;$TITLE_FILE&quot;)&quot; --description &quot;$(cat &quot;$DESC_FILE&quot;)
 rm -f .tmp/mr-title.txt .tmp/mr-desc.md
 ```
-### 步骤 7：追加 MR URL 到模块报告 § ⑫ 并 commit
+解析返回的 `IID` 和 `URL`，赋给 `MR_IID` / `MR_URL`（对应 5.5 命中时复用 `EXISTING_IID` / `EXISTING_URL`）。
+
+### 步骤 7：回写 docs/08 的 MR 字段并 commit（durable state 先持久化）
+
+> 先写 docs/08 再追模块报告——这样如果步骤 8 失败，重跑时 5.5 能直接识别已有 MR 且 docs/08 已含 IID，避免状态不一致。
-- 解析返回的 MR URL 和 IID（`<iid>`）。
-- `Edit docs/superpowers/module-reports/<date>-<module_id>.md` 的 § ⑫：把 `{{mr_url}}` 占位替换为实际 URL（若已替换过，追加一行）。
-- `Bash`: `git add docs/superpowers/module-reports/<date>-<module_id>.md && git commit -m "docs(<module_id>): record MR !<iid> link in module report"`。
+- `Edit docs/08-模块任务管理.md`：把当前模块条目的 `  - MR: —` 改为 `  - MR: !<MR_IID>`（只改一行）。docs/08 § 二 中 `MR:` 是唯一动态字段。
+- `Bash`: `git add docs/08-模块任务管理.md && git commit -m "chore(<module_id>): record MR !<MR_IID> in docs/08"`。
-### 步骤 8：回写 docs/08 的 MR 字段并 commit
+### 步骤 8：追加 MR URL 到模块报告 § ⑫ 并 commit
-- `Edit docs/08-模块任务管理.md`：把当前模块条目的 `  - MR: —` 改为 `  - MR: !<iid>`（只改一行）。docs/08 § 二 中 `MR:` 是唯一动态字段。
-- `Bash`: `git add docs/08-模块任务管理.md && git commit -m "chore(<module_id>): record MR !<iid> in docs/08"`。
+- `Edit docs/superpowers/module-reports/<date>-<module_id>.md` 的 § ⑫：把 `{{mr_url}}` 占位替换为 `<MR_URL>`（若已替换过，追加一行）。
+- `Bash`: `git add docs/superpowers/module-reports/<date>-<module_id>.md && git commit -m "docs(<module_id>): record MR !<MR_IID> link in module report"`。
 ### 步骤 9：再次 push
-步骤 3 的 push 之后，步骤 7 和 8 又产生了两个新 commit（MR link + docs/08 MR iid）。必须再次 push 让 MR 自动更新 commit 列表 + diff：
+步骤 3 的 push 之后，步骤 7、8 又产生了两个新 commit（docs/08 MR iid + 模块报告 MR link）。必须再次 push 让 MR 自动更新 commit 列表 + diff：
 `Bash`: `git push origin <current_branch>`
@@ -111,13 +127,13 @@ rm -f .tmp/mr-title.txt .tmp/mr-desc.md
 ### 步骤 11：停止 — 等待人工 Approve + Merge
-用户合并后再次运行 `/erp-workflow:erp-coding-start`，入口会自动检测 MR merged → `git checkout main` + `git pull --ff-only` 同步远程 + 派发下一模块。
+用户合并后再次运行 `/erp-workflow:erp-coding-start`，入口会自动检测 MR merged → 探测默认分支（`main` 或 `master`）→ `git checkout <默认分支>` + `git pull --ff-only origin <默认分支>` 同步远程 → 派发下一模块。
 ## 设计要点
-- **main 是 protected branch**，只能通过 MR 修改。MR diff 覆盖代码、模块报告、test-gate evidence、cross-module log，以及 docs/08 的 `MR: !<iid>` 字段。
+- **默认分支（main 或 master）是 protected branch**，只能通过 MR 修改。MR diff 覆盖代码、模块报告、test-gate evidence、cross-module log，以及 docs/08 的 `MR: !<iid>` 字段。
 - **完成信号以 MR state 为准**：docs/08 § 二 中仅 `MR:` 字段在 `—` / `!<iid>` 之间变化，避免提前合并未完成模块的顺序错误。
-- **worktree 干净前置**（步骤 2）：保证 test-gate.md、module-report.md、cross-module log.md 都已进 repo，审计证据完整；防止下次 coding-start `git checkout main` 遇到 dirty state。
+- **worktree 干净前置**（步骤 2）：保证 test-gate.md、module-report.md、cross-module log.md 都已进 repo，审计证据完整；防止下次 coding-start 切回默认分支时遇到 dirty state。
 ## 参考
@@ -15,4 +15,4 @@
 ## 审核入口
 - 本 MR = 模块 `{{module_id}}` 的唯一人工介入点
-- Approve + Merge 后，下次用户运行 `/erp-workflow:erp-coding-start` 时入口会自动扫描到 `glab mr view state=merged`，`git pull --ff-only` 同步 main 并推进下一模块
+- Approve + Merge 后，下次用户运行 `/erp-workflow:erp-coding-start` 时入口会自动扫描到 `glab mr view state=merged`，探测默认分支后 `git pull --ff-only` 同步并推进下一模块
 ---
 name: erp-coding-start
-description: B é˜¶æ®µï¼ˆCodingï¼‰å…¥å£ã€‚å…ˆéªŒè¯ Plan å·²å®Œæˆï¼›æŒ‰ docs/02 Â§ äºŒ REQ å¼€å‘é¡ºåºæ¸…å•æ‰«æï¼Œå¯¹æ¯ä¸ª REQ æ‰€å±žæ¨¡å—ç”¨ docs/08 çš„ `MR:` å—æ®µ + `glab mr view state` åˆ¤å®šæ˜¯å¦å®Œæˆâ€”â€”merged è·³è¿‡ï¼Œ`â€”` æˆ– opened/closed é€‰ä¸ºå½“å‰æ¨¡å—å¹¶æ´¾å‘åˆ° erp-module-startã€‚æ´¾å‘å‰å…ˆ git checkout main + pull --ff-only ä¿æŒ base æœ€æ–°ã€‚
+description: B é˜¶æ®µï¼ˆCodingï¼‰å…¥å£ã€‚å…ˆéªŒè¯ Plan å·²å®Œæˆï¼›æŒ‰ docs/02 Â§ äºŒ REQ å¼€å‘é¡ºåºæ¸…å•æ‰«æï¼Œå¯¹æ¯ä¸ª REQ æ‰€å±žæ¨¡å—ç”¨ docs/08 çš„ `MR:` å—æ®µ + `glab mr view state` åˆ¤å®šæ˜¯å¦å®Œæˆâ€”â€”merged è·³è¿‡ï¼Œ`â€”` æˆ– opened/closed é€‰ä¸ºå½“å‰æ¨¡å—å¹¶æ´¾å‘åˆ° erp-module-startã€‚æ´¾å‘å‰è‡ªåŠ¨æŽ¢æµ‹é»˜è®¤åˆ†æ”¯ï¼ˆmain / masterï¼‰å¹¶ git checkout + pull --ff-only ä¿æŒ base æœ€æ–°ã€‚
 user-invocable: true
-allowed-tools: Skill Read Glob Grep Bash(glab mr *) Bash(git branch *) Bash(git checkout *) Bash(git pull *) Bash(git status *)
+allowed-tools: Skill Read Glob Grep Bash(glab mr *) Bash(git branch *) Bash(git checkout *) Bash(git pull *) Bash(git status *) Bash(git symbolic-ref *) Bash(sed *)
 ---
 **æ‰€æœ‰è¾“å‡ºå¿…é¡»ä½¿ç”¨ä¸æ–‡ã€‚**
-B é˜¶æ®µï¼ˆCodingï¼‰çš„å…¥å£åˆ†å‘å™¨ã€‚èŒè´£ï¼š**éªŒè¯ Plan å·²å®Œæˆ â†’ æŒ‰ docs/02 Â§ äºŒ REQ åº + MR state å®šä½å½“å‰æ¨¡å— â†’ åˆ‡å›ž main å¹¶åŒæ¥è¿œç¨‹ â†’ æ´¾å‘ erp-module-start**ã€‚ä¸ç›´æŽ¥ç”Ÿæˆä»»ä½•æ–‡ä»¶ã€‚å¼€å‘é¡ºåºä»¥ `docs/02 Â§ äºŒ` ä¸ºå‡†ï¼›å®Œæˆåˆ¤å®šä»¥ `docs/08 æ¡ç›®çš„ MR: å—æ®µ + glab mr view state` ä¸ºå‡†ã€‚
+B é˜¶æ®µï¼ˆCodingï¼‰çš„å…¥å£åˆ†å‘å™¨ã€‚èŒè´£ï¼š**éªŒè¯ Plan å·²å®Œæˆ â†’ æŒ‰ docs/02 Â§ äºŒ REQ åº + MR state å®šä½å½“å‰æ¨¡å— â†’ åˆ‡å›žé»˜è®¤åˆ†æ”¯å¹¶åŒæ¥è¿œç¨‹ â†’ æ´¾å‘ erp-module-start**ã€‚ä¸ç›´æŽ¥ç”Ÿæˆä»»ä½•æ–‡ä»¶ã€‚å¼€å‘é¡ºåºä»¥ `docs/02 Â§ äºŒ` ä¸ºå‡†ï¼›å®Œæˆåˆ¤å®šä»¥ `docs/08 æ¡ç›®çš„ MR: å—æ®µ + glab mr view state` ä¸ºå‡†ã€‚é»˜è®¤åˆ†æ”¯ï¼ˆ`main` æˆ– `master`ï¼‰åœ¨æ¥éª¤ 4 è‡ªåŠ¨æŽ¢æµ‹ï¼Œä¸ç¡¬ç¼–ç ã€‚
 ## æ‰§è¡Œæ¥éª¤
@@ -60,14 +60,28 @@ B é˜¶æ®µï¼ˆCodingï¼‰çš„å…¥å£åˆ†å‘å™¨ã€‚èŒè´£ï¼š**éªŒè¯ Plan å·²å®Œæˆ â†’ æŒ
    å¹¶**åœä¸‹**ã€‚
 6. å‘½ä¸åŽï¼šè®°å½• `current_module` çš„ `MR:` å—æ®µå€¼ï¼ˆ`â€”` / `!<iid>-opened` / `!<iid>-closed` / `!<iid>-æŸ¥ä¸åˆ°`ï¼Œç”¨äºŽæ¥éª¤ 5 æ¨ªå¹…å±•ç¤ºï¼‰ã€‚
-### æ¥éª¤ 4ï¼šåˆ‡å›ž main + åŒæ¥è¿œç¨‹ï¼ˆå‡†å¤‡ module-start åˆ‡æ–°åˆ†æ”¯çš„å¹²å‡€ baseï¼‰
+### æ¥éª¤ 4ï¼šæŽ¢æµ‹é»˜è®¤åˆ†æ”¯ + åˆ‡å›žå¹¶åŒæ¥è¿œç¨‹ï¼ˆå‡†å¤‡ module-start åˆ‡æ–°åˆ†æ”¯çš„å¹²å‡€ baseï¼‰
+
+4.0 **æŽ¢æµ‹é»˜è®¤åˆ†æ”¯**ï¼š
+
+```bash
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+if [ -z "$DEFAULT_BRANCH" ]; then
+  # HEAD æœªè®¾ç½®ï¼Œå›žé€€ï¼šåœ¨ main / master é‡Œå–ç¬¬ä¸€ä¸ªå®žé™…å˜åœ¨çš„è¿œç¨‹åˆ†æ”¯
+  DEFAULT_BRANCH=$(git branch -r --format='%(refname:short)' | grep -E '^origin/(main|master)$' | head -1 | sed 's|^origin/||')
+fi
+```
+
+- `DEFAULT_BRANCH` ä¸ºç©º â†’ æ‰“å°é”™è¯¯å¹¶**åœä¸‹**ï¼ˆæ—¢æ—  `origin/main` ä¹Ÿæ—  `origin/master`ï¼Œè¯´æ˜Žè¿œç¨‹æœªå°±ç»ªï¼Œæç¤ºç”¨æˆ·å…ˆå®Œæˆ Plan çš„é¦–æ¬¡ push æˆ– `git remote set-head origin -a` è®¾ç½® HEADï¼‰ã€‚
+
+4.1 **åˆ‡å›ž + åŒæ¥**ï¼š
 - `Bash`: `git branch --show-current` â†’ `current_branch`ã€‚
-- è‹¥ `current_branch != main`ï¼š
+- è‹¥ `current_branch != $DEFAULT_BRANCH`ï¼š
   - `Bash`: `git status --porcelain`ï¼›éžç©º â†’ æ‰“å°ï¼š
     ```
     â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”
-     [erp-coding-start] âš ï¸ å½“å‰åˆ†æ”¯ <current_branch> æœ‰æœªæäº¤æ”¹åŠ¨ï¼Œæ— æ³•åˆ‡æ¢åˆ° main
+     [erp-coding-start] âš ï¸ å½“å‰åˆ†æ”¯ <current_branch> æœ‰æœªæäº¤æ”¹åŠ¨ï¼Œæ— æ³•åˆ‡æ¢åˆ° <DEFAULT_BRANCH>
      <git status è¾“å‡º>
@@ -75,17 +89,17 @@ B é˜¶æ®µï¼ˆCodingï¼‰çš„å…¥å£åˆ†å‘å™¨ã€‚èŒè´£ï¼š**éªŒè¯ Plan å·²å®Œæˆ â†’ æŒ
     â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”
     ```
     å¹¶**åœä¸‹**ã€‚
-  - `Bash`: `git checkout main`ã€‚
-- `Bash`: `git pull --ff-only origin main`ã€‚
+  - `Bash`: `git checkout "$DEFAULT_BRANCH"`ã€‚
+- `Bash`: `git pull --ff-only origin "$DEFAULT_BRANCH"`ã€‚
   - å¤±è´¥ï¼ˆéž fast-forward / ç½‘ç»œ / å†²çªï¼‰â†’ æ‰“å°é”™è¯¯æ¨ªå¹…ï¼š
     ```
     â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”
-     [erp-coding-start] âš ï¸ åŒæ¥ main å¤±è´¥
+     [erp-coding-start] âš ï¸ åŒæ¥ <DEFAULT_BRANCH> å¤±è´¥
-     æœ¬åœ° main æ— æ³• fast-forward åˆ° remoteã€‚è¯·æ‰‹å·¥å¤„ç†ï¼š
+     æœ¬åœ° <DEFAULT_BRANCH> æ— æ³• fast-forward åˆ° remoteã€‚è¯·æ‰‹å·¥å¤„ç†ï¼š
        git status
-       git log main..origin/main   # è¿œç¨‹é¢†å…ˆçš„ commit
-       git log origin/main..main   # æœ¬åœ°æœªæŽ¨çš„ commit
+       git log <DEFAULT_BRANCH>..origin/<DEFAULT_BRANCH>   # è¿œç¨‹é¢†å…ˆçš„ commit
+       git log origin/<DEFAULT_BRANCH>..<DEFAULT_BRANCH>   # æœ¬åœ°æœªæŽ¨çš„ commit
      ä¿®å¤åŽé‡æ–°è¿è¡Œ /erp-workflow:erp-coding-startã€‚
     â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”
     ```
@@ -110,7 +124,7 @@ B é˜¶æ®µï¼ˆCodingï¼‰çš„å…¥å£åˆ†å‘å™¨ã€‚èŒè´£ï¼š**éªŒè¯ Plan å·²å®Œæˆ â†’ æŒ
 ## è®¾è®¡è¦ç‚¹
 - **å®Œæˆåˆ¤å®šç›´æŽ¥è¯»å– `MR:` å—æ®µ + `glab mr view state`**ï¼šMR æœª merge å‰ docs/08 æ²¡æœ‰ä»»ä½•"å·²å®Œæˆ"æ ‡è®°ï¼›ç”¨æˆ·æå‰è§¦å‘ coding-start æ—¶ï¼Œæ¥éª¤ 3 æ‰«æåˆ° MR opened ä»ä¼šé€‰ä¸å½“å‰æ¨¡å—ï¼Œmodule-start ä¼š `git checkout module-<id>` å›žåˆ°åŽŸåˆ†æ”¯ç»§ç»ï¼Œä¸ä¼šè·³åˆ°ä¸‹ä¸€æ¨¡å—ã€‚
-- **æ¯æ¬¡æ´¾å‘å‰éƒ½ pull main**ï¼šä»£ç åŒæ¥çš„åŒæ—¶ï¼Œä¹Ÿä¿è¯ module-start åˆ‡å‡ºæ–°åˆ†æ”¯æ—¶ base æ–°é²œã€‚
+- **æ¯æ¬¡æ´¾å‘å‰éƒ½ pull é»˜è®¤åˆ†æ”¯**ï¼šä»£ç åŒæ¥çš„åŒæ—¶ï¼Œä¹Ÿä¿è¯ module-start åˆ‡å‡ºæ–°åˆ†æ”¯æ—¶ base æ–°é²œã€‚é»˜è®¤åˆ†æ”¯ç”±æ¥éª¤ 4.0 æŽ¢æµ‹ï¼ˆmain æˆ– masterï¼‰ï¼Œä¸ç¡¬ç¼–ç ã€‚
 ## å‚è€ƒ
@@ -64,10 +64,18 @@ A 阶段所有 checkbox 均 `[x]`。因无下游 A skill 接手，本步骤**自
  ⚠️ 进入 B 阶段前必须完成：
    1. 人工通读 docs/01~10 + CLAUDE.md + sql/migrations/V1 + 各 scripts/*
-   2. 把全部 Plan 产物 commit 到 main 分支：
+
+   2. 把全部 Plan 产物 commit：
         git add -A && git commit -m "chore: plan phase A0~A5 done"
-   3. 建 Plan MR 提交团队审核，合并后 main 成为 B 阶段每个模块分支的基线
-   4. MR 合并后再运行 /erp-workflow:erp-coding-start 进入 B 阶段
+
+   3. 推到远程：
+      git remote add origin <gitlab-url>   # 若尚未添加
+      git push --no-verify -u origin master
+      # 首次 push 用 --no-verify 跳过 pre-push 的 test.sh；
+      # 本地 DB 尚未就位、scripts/test.sh 此时必然失败，属正常
+      # push 完成后到 GitLab UI 把 master（或 main）设为 protected
+
+   4. main（或 master）就绪后，再运行 /erp-workflow:erp-coding-start
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 ---
 name: erp-red-flag-check
-description: 在每个功能循环步骤和生成重要制品前运行。检查 CLAUDE.md 中的 6 项红旗清单，命中任一项则追加 Blocker 到计划文件并停止。
+description: 在每个功能循环步骤和生成重要制品前运行。检查 CLAUDE.md 中的 3 项红旗清单，命中任一项则追加 Blocker 到计划文件并停止。
 user-invocable: false
 allowed-tools: Read Write Bash(mysql *)
 ---
@@ -11,27 +11,26 @@ allowed-tools: Read Write Bash(mysql *)
 ## 说明
-验证 CLAUDE.md § 🚩 静默执行红旗清单中的 6 项均未触发。命中任一项则中断。
+验证 CLAUDE.md § 🚩 静默执行红旗清单中的 3 项均未触发。命中任一项则中断。
+
+> 需求歧义 / schema 缺口 / 技术栈外组件引入等场景由各 feature-* skill 的 `AskUserQuestion` 流程承接，不进入本清单，不会在这里命中。
 ## 调用时机
 - 每个功能循环步骤开始前（3.1-3.5）
 - 生成模块级制品前（模块报告、MR 描述）
-- 用户请求涉及 schema 冲突、技术栈边界或外部依赖时
+- 用户请求涉及外部依赖、环境凭据变更时
-## 检查清单（6 项 — 权威来源：CLAUDE.md）
+## 检查清单（3 项 — 权威来源：CLAUDE.md）
-1. **需求与 schema 冲突** — 所需字段/表在实时 schema 中不存在
-2. **需求本身歧义** — 存在两种或以上合理解读
-3. **超技术栈边界** — 需要 CLAUDE.md 技术栈表以外的框架/中间件
-4. **测试反复失败** — 同一功能中同一测试连续 10 次修复失败
-5. **要改密钥/账密/包名** — 涉及 `docs/07-环境配置.md` 中的人工填写字段
-6. **外部接口不可达** — 第三方 API / 证书 / 网络问题
+1. **测试反复失败** — 同一功能中同一测试连续 10 次修复失败
+2. **要改密钥/账密/包名** — 涉及 `docs/07-环境配置.md` 中的人工填写字段
+3. **外部接口不可达** — 第三方 API / 证书 / 网络问题
 ## 执行步骤
 1. 读取当前功能的规格/计划文件路径（从对话或 `docs/08` 获取）。
-2. 逐项检查 6 个红旗。如果全部未命中 → 输出 `red-flag-check: 通过`，退出。
+2. 逐项检查 3 个红旗。如果全部未命中 → 输出 `red-flag-check: 通过`，退出。
 3. 命中时：
    - 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/red-flag-block-template.md`
    - 填充槽位（flag_number、flag_name、description、affected_scope、recommendation、decision_needed）
@@ -46,5 +45,5 @@ allowed-tools: Read Write Bash(mysql *)
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/red-flag-block-template.md`
-- `CLAUDE.md` § 🚩 静默执行红旗清单（权威 6 条）
+- `CLAUDE.md` § 🚩 静默执行红旗清单（权威 3 条）
 - `CLAUDE.md` § 🟡 软规则（S2 跨模块改动，不触发红旗但需留痕）
 ## 🚩 Blocker
-**红旗编号**: {{flag_number}}  (1-6，对应 CLAUDE.md 🚩 静默执行红旗清单)
+**红旗编号**: {{flag_number}}  (1-3，对应 CLAUDE.md 🚩 静默执行红旗清单)
 **红旗名称**: {{flag_name}}
 **问题描述**: {{description}}
 **影响范围**: {{affected_scope}}
@@ -2,7 +2,7 @@
 name: erp-db-design-gen
 description: A4 DB 设计生成 + REQ 回填——用 mysql CLI 反查 schema 生成 docs/03-数据库设计文档.md；然后用 Grep 在 docs/01-需求清单/*.md 定位 TBD(A4 自动补) 替换为实际表/字段引用。
 user-invocable: false
-allowed-tools: Read Write Edit Grep Glob Skill Bash(mysql *) Bash(source *)
+allowed-tools: Read Write Edit Grep Glob Skill Bash(mysql *) Bash(set *) Bash(. .env.local)
 ---
 **所有输出必须使用中文。**
@@ -36,10 +36,10 @@ allowed-tools: Read Write Edit Grep Glob Skill Bash(mysql *) Bash(source *)
 ### A. 查询实时 schema
-用 `Bash` source `.env.local` 后查询：
+用 `Bash` 加载 `.env.local` 后查询（用 `set -a; . ...; set +a` 替代 `source`，避免密码中的 shell 特殊字符被展开）：
 ```bash
-source .env.local
+set -a; . .env.local; set +a
 MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD} -N -B"
 # 表列表 + 注释
@@ -2,7 +2,7 @@
 name: erp-db-init
 description: A3 验证 MySQL 连接 + 导出当前 schema 为 `sql/migrations/V1__initial_schema.sql`（Flyway 初始 migration，DDL only）+ 导出当前数据为 `sql/seed-data.sql`（INSERT only）。不执行任何 DDL。
 user-invocable: false
-allowed-tools: Read Write Edit Glob Skill Bash(mkdir *) Bash(mysql *) Bash(mysqldump *) Bash(source *) Bash(sed *) Bash(cat *) Bash(rm sql/migrations/*.raw) Bash(rm sql/*.raw) Bash(grep *)
+allowed-tools: Read Write Edit Glob Skill Bash(mkdir *) Bash(mysql *) Bash(mysqldump *) Bash(set *) Bash(. .env.local) Bash(sed *) Bash(cat *) Bash(rm sql/migrations/*.raw) Bash(rm sql/*.raw) Bash(grep *)
 ---
 **所有输出必须使用中文。**
@@ -47,12 +47,15 @@ allowed-tools: Read Write Edit Glob Skill Bash(mkdir *) Bash(mysql *) Bash(mysql
 ### B. 验证 MySQL 连接
-用 `Bash` 执行（先 `source .env.local` 加载变量）：
+用 `Bash` 执行（先加载 `.env.local` 变量，用 `set -a; . ...; set +a` 避免 shell 展开密码中的特殊字符）：
 ```bash
-source .env.local && mysql -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" -e "USE \`$DB_SCHEMA\`; SHOW TABLES;"
+set -a; . .env.local; set +a
+mysql -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" -e "USE \`$DB_SCHEMA\`; SHOW TABLES;"
 ```
+> 注：密码中含 `$`、`` ` ``、空格、`!` 等字符时，`.env.local` 需用单引号包裹值，例如 `DB_PASSWORD='p@ss$w0rd!'`。`set -a; . file; set +a` 与 `source` 行为一致但更明确地声明"按 KEY=VALUE 加载并导出"，配合单引号可避免展开。
+
 - **成功** → 记录表列表，继续步骤 C。
 - **失败** → 向用户输出具体错误（认证失败 / schema 不存在 / 主机不可达等），提示检查 `.env.local`，**停下**。
@@ -61,7 +64,9 @@ source .env.local &amp;&amp; mysql -h&quot;$DB_HOST&quot; -P&quot;$DB_PORT&quot; -u&quot;$DB_USER&quot; -p&quot;$DB_PASSWOR
 用 `Bash` 执行 mysqldump（**仅 DDL，不含数据**）：
 ```bash
-mkdir -p sql/migrations && source .env.local && mysqldump --no-data --skip-comments -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" > sql/migrations/V1__initial_schema.sql.raw
+mkdir -p sql/migrations
+set -a; . .env.local; set +a
+mysqldump --no-data --skip-comments -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" > sql/migrations/V1__initial_schema.sql.raw
 ```
 如果 `mysqldump` 命令不存在，向用户输出具体错误（提示安装 `mysql-client` / `brew install mysql-client` 等）并**停下**（mysql 和 mysqldump 是 A0 `erp-project-init` 的前置依赖，正常情况下应已就绪）。
@@ -73,7 +78,7 @@ mkdir -p sql/migrations &amp;&amp; source .env.local &amp;&amp; mysqldump --no-data --skip-comme
 ```bash
 PROJECT="<从 CLAUDE.md 读到的项目名称>"
 TS="$(date -u +%FT%TZ)"
-source .env.local
+set -a; . .env.local; set +a
 {
   sed -e "s|{{project_name}}|$PROJECT|g" \
       -e "s|{{timestamp}}|$TS|g" \
@@ -94,7 +99,8 @@ rm sql/migrations/V1__initial_schema.sql.raw
 用 `Bash` 执行 mysqldump（**仅数据，INSERT only**）：
 ```bash
-source .env.local && mysqldump --no-create-info --complete-insert --skip-comments --skip-extended-insert \
+set -a; . .env.local; set +a
+mysqldump --no-create-info --complete-insert --skip-comments --skip-extended-insert \
   -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" > sql/seed-data.sql.raw
 ```
@@ -103,7 +109,7 @@ source .env.local &amp;&amp; mysqldump --no-create-info --complete-insert --skip-comment
 ```bash
 PROJECT="<从 CLAUDE.md 读到的项目名称>"
 TS="$(date -u +%FT%TZ)"
-source .env.local
+set -a; . .env.local; set +a
 {
   sed -e "s|{{project_name}}|$PROJECT|g" \
       -e "s|{{timestamp}}|$TS|g" \
@@ -146,7 +152,7 @@ rm sql/seed-data.sql.raw
 ## 不变量
-- 密码通过 `.env.local` 经 `source` 注入，不硬编码在命令里。
+- 密码通过 `.env.local` 以 `set -a; . .env.local; set +a` 方式导出到环境变量，不硬编码在命令里；特殊字符需用单引号包裹。
 - 本 skill **只** 产生 V1 initial migration 和 seed-data.sql 快照；后续 V2/V3 及业务数据变化由 B 阶段 `erp-feature-tdd` 在 REQ 实现时写入。
 ## 参考
@@ -156,10 +156,27 @@ docs/08 已由 A0 erp-project-init 创建（含 Plan 进度骨架）。本步骤
     ⚠️ 进入 B 阶段前必须完成：
       1. 人工通读 docs/01~10 + CLAUDE.md + sql/migrations/V1 + 各 scripts/*
-      2. 把全部 Plan 产物 commit 到 main 分支：
+
+      2. 把全部 Plan 产物 commit：
            git add -A && git commit -m "chore: plan phase A0~A5 done"
-      3. 建 Plan MR 提交团队审核，合并后 main 成为 B 阶段每个模块分支的基线
-      4. MR 合并后再运行 /erp-workflow:erp-coding-start 进入 B 阶段
+
+      3. 推到远程，按仓库状态二选一：
+
+         情况 A — 远程仓库是全新的（尚无 main / master）：
+           git remote add origin <gitlab-url>   # 若尚未添加
+           git push --no-verify -u origin master
+           # 首次 push 用 --no-verify 跳过 pre-push 的 test.sh；
+           # 本地 DB 尚未就位、scripts/test.sh 此时必然失败，属正常
+           # push 完成后到 GitLab UI 把 master（或 main）设为 protected
+
+         情况 B — 远程已有 main 需要走 MR 审核：
+           git checkout -b plan-init
+           git push -u origin plan-init
+           # 在 GitLab 打开 plan-init → main 的 MR，审核并合并
+
+      4. main（或 master）就绪后，再运行 /erp-workflow:erp-coding-start
+         进入 B 阶段。届时 .env.local 应指向本地 MySQL（非共享远程 DB），
+         否则 B 阶段每次测试闸门都会因 setup-test-db.sh 的防护失败。
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    ```
@@ -63,7 +63,7 @@
 4. 自动 git push（.githooks/pre-push 会再执行一遍 scripts/test.sh 作为硬闸门）
    + glab mr create，报告嵌入 MR 描述
 5. 人工 review MR → Approve + Merge（人工动作，唯一人工介入点）
-6. 下次用户运行 `/erp-workflow:erp-coding-start` 时，入口自动检测到本模块 `glab mr view state=merged` → `git checkout main && git pull --ff-only` 同步远程 → 扫描下一模块并派发
+6. 下次用户运行 `/erp-workflow:erp-coding-start` 时，入口自动检测到本模块 `glab mr view state=merged`，探测默认分支（main / master）后 `git checkout <默认分支> && git pull --ff-only` 同步远程 → 扫描下一模块并派发
 7. 你**不需要**手工 Edit docs/08（模块元数据不变；下次 coding-start 自动扫描 MR state 判定是否完成）
 ```
@@ -96,7 +96,7 @@
 两层嵌套循环的详细步骤**全部固化到 skills**，CLAUDE.md 不展开。入口调 `/erp-workflow:erp-coding-start`，自动分发：
-- **模块循环（外层，Layer 2）** → `erp-module-start` → `erp-local-test-gate`（commit test-gate.md）→ `erp-module-report`（commit 模块报告 + cross-module log）→ `erp-mr-create`（worktree clean 校验 → push → 创建 MR → 追加 MR URL 到报告并 commit → 写 `MR: !<iid>` 到 docs/08 并 commit → 再次 push）→ 人工 Approve+Merge → 下次运行 `/erp-workflow:erp-coding-start` 扫描到本模块 `glab mr view merged` → `git pull --ff-only main` → 推进下一模块
+- **模块循环（外层，Layer 2）** → `erp-module-start` → `erp-local-test-gate`（commit test-gate.md）→ `erp-module-report`（commit 模块报告 + cross-module log）→ `erp-mr-create`（worktree clean 校验 → push → 创建 MR → 追加 MR URL 到报告并 commit → 写 `MR: !<iid>` 到 docs/08 并 commit → 再次 push）→ 人工 Approve+Merge → 下次运行 `/erp-workflow:erp-coding-start` 扫描到本模块 `glab mr view merged` → 探测默认分支并 `git pull --ff-only` → 推进下一模块
 - **功能循环（内层，Layer 3，每个 REQ-XXX-NNN 走一遍）** → `erp-feature-brainstorm` → `erp-feature-plan` → `erp-feature-tdd` → `erp-feature-verify` → `erp-feature-review`
 **本地测试闸门**: `erp-local-test-gate` 是 MR 前的唯一硬闸门，子会话执行 `scripts/test.sh`：脚本先由 `setup-test-db.sh` 清空库 → build / lint → 执行测试（Spring Boot 启动时 Flyway 自动 apply `sql/migrations/V*.sql`）→ e2e → 再次清库。详见 § 🧪 自测要求。`.githooks/pre-push` 在 push 时会再次执行 `scripts/test.sh` 作为兜底；`git push --no-verify` 被 hook `deny-no-verify.sh` 硬拦截。本项目不配置 GitLab CI/CD。
@@ -214,12 +214,11 @@ refactor(common): 统一响应格式包装
 | # | 红旗 | 例子 |
 | - | --- | --- |
-| 1 | **需求与 schema 不一致** | REQ 提到的字段/表在现有 schema 里不存在 → 先向用户确认「加一个 migration 新增 / 修正 REQ 理解」；得到答复后继续，**不走下方 Blocker 文件流程** |
-| 2 | **需求本身歧义** | spec 中某规则有两种合理解读，CC 无法判断 |
-| 3 | **超技术栈边界** | 需要引入 `docs/tech-stack.md` 以外的框架 / 中间件 |
-| 4 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 |
-| 5 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 |
-| 6 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题 |
+| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 |
+| 2 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 |
+| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题 |
+
+> 其余需要人类判断的场景（需求歧义 / schema 缺口 / 技术栈外组件引入）一律走普通 `AskUserQuestion` Q&A，不升格为红旗、不写 Blocker 文件。见下方「📘 技术栈外组件的处理规则」与各 feature-* skill 的 Q&A 流程。
 **命中红旗时的固定动作：**
@@ -232,7 +231,7 @@ refactor(common): 统一响应格式包装
 ```markdown
 ## ⚠️ 需要人工决策
-**红旗编号**: [1–6 中的某一条]
+**红旗编号**: [1–3 中的某一条]
 **问题描述**: [详细描述]
 **影响范围**: [影响哪些模块 / 功能]
 **我的建议**: [初步判断，可选]
@@ -241,6 +240,18 @@ refactor(common): 统一响应格式包装
 ---
+## 📘 技术栈外组件的处理规则
+
+brainstorm / plan 阶段若发现需要 `docs/04-技术规范.md § 零` 技术栈表之外的框架、中间件或关键库：
+
+1. 用 `AskUserQuestion` 询问用户（选项至少含：接受引入 / 换方案 / 拒绝）
+2. **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程
+3. **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛
+
+不写 Blocker 文件，不中断流程。
+
+---
+
 ## 🟡 软规则（允许继续，但有强制后续动作）
 以下情况 **不触发中断**，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。漏留痕 = 红旗。
@@ -101,7 +101,7 @@ cp &quot;${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh&quot; scripts/set
 ```bash
 #!/usr/bin/env bash
-# scripts/test.sh —— 合并到 main 前的唯一硬闸门。
+# scripts/test.sh —— 合并到默认分支（main / master）前的唯一硬闸门。
 # 顺序：setup-db → build → lint → unit+integration → e2e → reset-db
 # 由 .githooks/pre-push 和 erp-local-test-gate skill（通过子会话）调用。
-DB_HOST=【人工填写：MySQL host，例如 localhost】
+# .env.local — 本地开发凭据（入 .gitignore，不提交）
+#
+# 规则：
+# 1. 值含 `$`、反引号、空格、`!` 等 shell 特殊字符时，必须用单引号包裹：
+#      DB_PASSWORD='p@ss$w0rd!'
+#    否则 `set -a; . .env.local; set +a` 会做变量展开导致密码错乱。
+# 2. DB_HOST 建议保持 localhost / 127.0.0.1；非本地 host 会被 scripts/setup-test-db.sh 防护拒绝。
+# 3. DB_SCHEMA 建议命名含 test / _dev / _local / _ci，避免与生产库同名。
+
+DB_HOST=【人工填写：MySQL host，推荐 localhost】
 DB_PORT=【人工填写：MySQL port，默认 3306】
 DB_USER=【人工填写：开发账号名】
-DB_PASSWORD=【人工填写：对应密码】
-DB_SCHEMA=【人工填写：schema 名，例如 erp_dev】
+DB_PASSWORD=【人工填写：对应密码，含特殊字符时用单引号包裹】
+DB_SCHEMA=【人工填写：schema 名，推荐含 test/_dev/_local，例如 erp_dev】
 JWT_SECRET=【人工填写：JWT 签名密钥，256+ bit 随机串】
@@ -7,14 +7,44 @@
 #  - scripts/test.sh 开头：清空库，让 Spring 启动时 Flyway 从 V1 开始重放所有 migration
 #  - scripts/test.sh 结尾：清空库，避免测试遗留污染下次运行
 #  - 手动调试时：reset 到零状态
+#
+# 防护：本脚本只允许在本地 host + 测试库名上执行；非预期目标会被拒绝，
+# 避免 .env.local 误指向 staging/prod 时触发不可逆 DROP。
 set -euo pipefail
-source "$(dirname "$0")/../.env.local"
+ENV_FILE="$(dirname "$0")/../.env.local"
+[ -f "$ENV_FILE" ] || { echo "[setup-test-db] ⚠️ .env.local 不存在（$ENV_FILE）" >&2; exit 1; }
+
+# 用 set -a 加载，让 KEY=VALUE 导出为环境变量；密码中含特殊字符时 .env.local 请用单引号包裹
+set -a; . "$ENV_FILE"; set +a
+
+# 防护 1：只允许本地 host（localhost / 127.0.0.1 / ::1）
+case "${DB_HOST:-}" in
+  localhost|127.0.0.1|::1) ;;
+  *)
+    echo "[setup-test-db] ⚠️ 拒绝在非本地 host (${DB_HOST}) 上执行 DROP DATABASE" >&2
+    echo "  如确需对远程 DB 重置（少见，常属误配），请显式声明：TEST_DB_ALLOW_REMOTE=1 $0" >&2
+    [ "${TEST_DB_ALLOW_REMOTE:-0}" = "1" ] || exit 1
+    ;;
+esac
+
+# 防护 2：schema 名需像测试/开发库（含 test / _dev / _local），否则要求显式确认
+case "${DB_SCHEMA:-}" in
+  *test*|*_dev|*_local|*_ci)
+    ;;
+  *)
+    echo "[setup-test-db] ⚠️ schema '${DB_SCHEMA}' 不像测试库（期望命名含 test / _dev / _local / _ci）" >&2
+    echo "  如确为期望行为，请显式声明：TEST_DB_ALLOW_PROD_NAME=1 $0" >&2
+    [ "${TEST_DB_ALLOW_PROD_NAME:-0}" = "1" ] || exit 1
+    ;;
+esac
+
+# 防护 3：显式 banner，让人看见自己在 drop 什么
+echo "[setup-test-db] 即将 DROP + CREATE \`${DB_SCHEMA}\` on ${DB_HOST}:${DB_PORT}"
 MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD}"
-echo "[setup-test-db] drop + create database ${DB_SCHEMA}"
 $MYSQL_CMD -e "DROP DATABASE IF EXISTS \`${DB_SCHEMA}\`; CREATE DATABASE \`${DB_SCHEMA}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
 echo "[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts"